...
- The API should be RESTful (see here about the REST)
- The API should return the data in the format according to the 'Accept' request header. Use JSON (MIME type'application/json') when either the header is not set, or when the other formats aren't available. (Example: return XML if the 'Accept' header is 'application/xml', return CSV if the 'Accept' header is 'text/csv' etc.)
- The API should return the standard HTTP response codes depending on the result. (Example: return '200 OK' after the objects listing, return '201 Created' after the object creation, return '404 Not Found' if the object was not found etc.)
- The API should act accordingly to the request method (e.g. GET gets something, PUT creates somethingupdates something specific, POST creates a new object, etc).
- The URL (endpoint) of the API should abide to certain conventions (see section below).
- The Request should make use of several headers (see section below).
- The JSON response should have the same structure (see section below).
URL requirements of the API
Nico Should propose a format here 
All services are reachable from the frontend over /service/<servicename>/ and the API is reachable over /service/<servicename>/api. This is true for all services except for the core, which is also reachable over /. The service will not be aware of the prefix, meaning that /service/omsevents/abcdefg/file.jpg will actually reach the service omsevents under /abcdefg/file.jpg. Thus keeping this format is a task of oms-docker and the traefik configuration, it happens transparent to the service.
Parameters
HTTP supports a variety of passing arguments:
- As part of the link (ie. /api/users/3)
- As part of the query string (ie. /api/users?name=Bob)
- As part of the payload (ie. trough a form)
In general the following rules apply:
- If it is a selector of some kind (usually ID or name), put it in the link.
- If it is an additional filter / option of the selected object, put it in the query string.
- If it is none of these, or if it should remain a secret, put it in the payload.
See the core API as an example of this.
Request API requirements
A request should be a standard HTTP request to one of the endpoints of the microservice as defined by its API. The request should use one of the specified HTTP methods (for example: GET, POST, DELETE, etc.). In addition to this the header 'X-Auth-Token' is required to be (correctly) set for most endpoints.
Getting an X-Auth-Token
There are several ways to obtain an An X-Auth-Token :
- For a microservice you should follow this protocol.
- As a user you can request your access token from the http://localhost/api/login endpoint.
- Use the POST method, no headers special headers are required.
- Body:
- username: 'flaviu@glitch.ro'
- password: '1234'
can be requested through the login endpoint as specified in the core API.
Response API requirements
...
- success - Mandatory field. A boolean that represents if the API call was successful or not. Should always be true for the successful call.
- meta - Optional field. An object containing meta information, if any. (e.g. pagination data, timestamps etc.)
- data - Optional field. An object containing a single object, or an array in the case of when multiple objects are expected, that was requested/modified/deleted by the user.
- message - Optional field. A string containing a message to the user, useful on POST/PUT/DELETE requests.
...