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 2 parts which are standardized: The format of the response and the format of the url of the API endpoint, both have their own section on this page.

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 creates something, 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 

Request API requirements

Derk Snijders Will update this

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."
}

...

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

Unsuccessful response

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

...