Skip to main content

Standards

This section describes the Standards and conventions shared across all the endpoints of the API.

Resources​

The fundamental concept in any RESTful API is the resource. A resource is an object with a type, associated data, relationships to other resources, and a set of methods that operate on it. It represents a specific piece of information or functionality that can be accessed, modified or deleted using HTTP methods like GET, POST, PUT, DELETE, etc. Example Accounts, Subsribers, etc.

Headers​

  • X-Correlation-ID: In order to easily identify a request on all of 1GLOBAL's subsystems, we require that requesters create a unique identifier that will be sent on every request header when (X-Correlation-ID) using the api. This way we can easily identify a request or a sequence of events between both 1GLOBAL and the requester.
  • Idempotency-Key: To ensure a strong idempotent behavior comprising same responses, to prevent duplicate execution in case of retries after timeout and network outages, consider providing the Idempotency-Key header. Generally, this can be achieved by sending a client specific unique request key – that is not part of the resource.

Hypertext Application Language (HAL)​

HAL is an Internet Draft standard convention for defining hypermedia such as links to external resources within JSON or XML code. Our APIs follow this standard to describe links to other resources in the API. These links enable navigation to other resources directly from response payloads, making the integration with the API easier.

{
  ...
 "_links": {
    "self": {
      "href": "https://example.com/probs/1234"
    },
    "author": {
      "href": "https://example.com/users/john"
    }
  }
}

Pagination​

To protect the service against overload, as well as to support client side iteration and batch processing experience, resource listing endpoints implement cursor-based pagination.

The only input required is the page size -limit- and subsequent navigation can be done through the next/prev page links provided in each page's response payload.

To prevent misuse of the pagination feature, each API defines a maximum allowed page size (usually 50 or 100).

{
  ...
  "_links": {
    "self": { "href": "https://example.com/probs?limit=10" },
    "prev": { "href": "https://example.com/probs?cursor=MTY3NjE1ODU1MS8yNUMxOTgxRjA1RDU5MDAwMDAwMA%3D%3D&limit=10" },
    "next": { "href": "https://example.com/probs?cursor=MTY3NjEzMzkxMS8yNUMxMEYzNkJBODA1NTkwMDAwMDAw&limit=10" },
  }
}
selfA limit on the number of objects returned. Default limit value is 10.
prevA cursor for use in pagination. The page [prev] is the object ID defining place in the list and only items immediately preceding the item with that ID is returned.
nextA cursor for use in pagination. The page [next] is the object ID that defines your place in the list and only items immediately following the item with that ID is returned.

Error Codes​

APIs return the appropriate HTTP Status Codes to communicate the result of a request operation. The developer should be familiar with the semantics of the Common HTTP Status Codes categories:

  • 1xx: Informational
  • 2xx: Success
  • 3xx: Redirection
  • 4xx: Client Error
  • 5xx: Server Error

An error occurs whenever the request does not comply with the API specification, for example:

  • unknown parameter is specified
  • the parameter value is incorrect (e.g. a string is expected, but a number is received), does not match the expected format (e.g. a malformed e-mail address) or not part of the documented enum.