GitHubHelp

nitrix/centric-assignment

A REST API assignment for my interview at Centric Software.

★ 0Forks 0GoGitHub ↗Compare

README

centric-assignment

A REST API assignment for my interview at Centric Software.

Table of contents

  1. Features
  2. Build instructions
  3. Codebase structure
  4. API documentation
    1. Query parameters
    2. Rate limiting
    3. Endpoints
    4. Entities
      1. Product
  5. License

Features

  • RESTful endpoints.
  • Supports versioning.
  • Transparent rate-limiting.
  • Proper HTTP error handling.
  • Maximum request durations.
  • ISO8601 timestamps throughout.
  • In-memory database.

Build instructions

You will need git and go installed to build the project manually.

Alternatively, there are release builds available and an online version.

git clone https://github.com/nitrix/centric-assignment
go build

You can then run the executable by launching centric-assignment on Unix or centric-assignment.exe on Windows. Go can also do it for you with the command go run.

Codebase structure

  • controllers API endpoints organized by version; they handle incoming requests.
  • middlewares Small functions that runs before and/or after requests.
  • models Data holders with a few common operations, modeling the domain.
  • repositories Data sources/sinks, usually operates on a database.

The root is reserved for the main file and other various configuration files.

API documentation

Query parameters

Listing endpoints accepts various parameters to control the pagination and filtering.

Name Purpose Description
page Pagination The page number, counting from 0 as the first page. Negative values are ignored.
perPage Pagination The maximum number of entries per page. Defaults to 10, capped to 1000. Negative values are ignored.
filter Filtering Filters the results by a desired value for a specific field. That field must exist and the value is matched exactly. Multiple of those filters are allowed, the query string key is always filter while the query string value is a concatenation of the field of interest and the desired value, joined by a colon : character.

An example complete query string could look like this:

?page=5&perPage=250&filter=category:shoes&filter=color:blue

No worries, additional colons within the filters are not a problem for matching.

Rate limiting

The API currently allows 100 requests for each real-time minute, resetting every new minute.

You can query the root of your API version (e.g. /v1) for details about your usage count, your maximum quota and when is the next reset.

Upon reaching the maximum, requests are rejected with HTTP code 429 (too many requests).

Endpoints

Important note: Text in-between curly braces like {id} are just placeholders for documentation purposes and must be substituted in their entirety (including the curly braces) by the actual information they stand for. Very frequently that will be a UUID universal unique identifier.

Method Endpoint Short description Paginated / filtered
GET /v1 Information and usage metadata. No
POST /v1/products Creates a product. No
GET /v1/products/{id} Fetches one product by it's id. No
GET /v1/products List all products. Yes

Entities

Product

Field name Field type Additional info Needed JSON example
id string UUIDv4 No "b6afac37-cf9a-4fd4-8257-f096dbb5d34d"
name string Yes "Red Shirt"
description string Yes "Red hugo boss shirt"
brand string Yes "Hugo Boss"
tags array of string Yes ["red", "shirt", "slim fit"]
category string Yes "apparel"
created_at string ISO8601 datetime No "2017-04-15T01:02:03Z"

Requests don't need the id and created_at fields (it's ignored), while responses are guaranteed to provide them.

License

This is free and unencumbered software released into the public domain. See the UNLICENSE file for more details.

Contributors

nitrix

Issues