This page describes the API features that should be standardized across every microservices. Abiding to these conventions is in most cases a requirement, so stick to it!

There are 3 parts which are standardized: The format of the request, the format of the response and the format of the URL of the API endpoint, all three have their own section on this page.

As a general tip: use your browser's network tracking developer tools to inspect the behavior of what already is!

General API requirements

Each microservice's API should return the data in the same way, defined below:

• 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 updates 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

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 

An X-Auth-Token can be requested through the login endpoint as specified in the core API.

Response API requirements

Each response should have the same structure, depending on the request and the result.

The response structures for the successful and unsuccessful request are slightly different.

Successful response

{
  "success": true,
  "meta": {},
  "data": [],
  "message": "A message to user."
}

• 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 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.

In the response, either the 'data' or 'message' fields should be presented.

Unsuccessful response

{
  "success": false,
  "errors": [],
  "message": "An error has occured."
}

• success - Mandatory field. A boolean that represents if the API call was successful or not. Should always be false for the unsuccessful call.
• errors - Optional field. An array containing errors' details, if available. (e.g. validation errors)
• message - Mandatory field. A string containing an error message.