Base response for API calls.

{
  "meta": {
    "timestamp": 1597166699457,
    "transactionId": "70169d77-c165-4795-9932-35b8a3af96fb",
    "explain": "a descriptive text"
  },
  "pagination": {
    "offset": "5f466c67e047e3293115e2ec", 
    "limit": 10,
    "next": "5f466c67e047e3293115e2ec", 
    "page": 5,
    "pages": 40,
    "total": 1000
  },
  "errors": {
    "reason": "failure reason",
    "details": [ {} ]   
  }, 
  "data": {}, 
  "items": [ {} ]
}

Meta

The meta segment is dedicated to metadata regarding the call itself.

Meta	Description
timestamp	Call’s time mark
transactionId	Call’s transaction ID, this will help our teams to locate issues faster if arose
explain	Could be anything, is just a useful message regarding the operation or the call

Pagination

This is an optional segment that we will use with search endpoints or any other that needs to paginate its results.

Pagination	Description
offset	How many items we are skipping in this call, this establish the initial point.
limit	How many items per page we want to fetch in this call.
next	Which is the next item to be queried to keep continuity when passing pages. This is meant to be used with offset.
page	The current page indicator, this is useful for clients and help preventing them to.
pages	Total pages, this value its relative and will depends on the total items in the collection and the limit used on the call.
total	Total elements in the collection at the time of the invocation.

Errors

The main error indicator always is the HTTP status code, however, this is a flexible placeholder if an endpoint wants to give more insights about the reasons of a failure.

The error segment is a free hand map that could contain any key and value combination.

Error	Description
reason	The failure main reason as a descriptive text.
details	A key -> value map to add additional information about the error.