Skip to main content

Standards

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.

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 (using limit parameter) 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" },
  }
}

Errors​

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