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.

Table of Contents

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

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 multiple objects, 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.

Standardized API