Skip to main content

RESTful APIs

The RESTful APIs require the following components:

  • Unique resourse identifier (URI): It is the request endpoint that specificies the client action
  • HTTP Method: It is instructs ths server what to do at the URI given
    • GET: Request data from the API.
    • POST: Send data in the request body to the API to create a data object.
    • PUT: Send data in the request body to the API to create or update a data object.
    • PATCH: Send data in the request body to the API to update a data object.

The API requests are managed through a HTTPS connection with content body in JSON format.

JSON format

All API requests and responses are sent and returned in JSON format and should be parsed according to standard JSON specifications.

Field names​

  • Case sensitive
  • Use snake_case
  • The order of fields in requests and responses is not guaranteed and should not be relied upon

Data types​

  • Standard JSON data types are used which include strings, numbers, booleans, objects, arrays, and null values.

Forward compatibility​

  • Additional fields may be added to the requests and responses in future versions and unless stated otherwise, these should be ignored.

HTTP status code​

Status codes are embedded in the response HTTP header. It indicates if the request is fulfilled.

The MSL Edge API makes use of the following:

  • 2xx: Success – Indicates the client’s request was accepted successfully.
  • 4xx: Client Error – This status codes points issues at the clients side.
  • 5xx: Server Error – It points to an error on the server side.

Response Body​

The response body contains the data returned by the API for the requested operation. Different endpoints return different data, which is represented as one or more JSON properties.

In some cases, the documentation may describe properties that are not included in the response. This occurs when there is no data available for those properties. When this happens, the properties are omitted from the response and should be treated as having null values.

It should not be assumed that all documented properties will always be present in the response.

Successful responses​

Successful responses return a JSON object containing one or more fields, depending on the endpoint.

Example:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 900,
  "type": "Bearer"
}

Error responses​

When a request fails, the API returns a JSON object along with an appropriate HTTP status code.

Example:

{
  "code": "4010001"
}

The code field provides a machine-readable identifier for the error. The HTTP status code should be used to determine the general error category.