Base Response

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.

MetaDescription
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.

PaginationDescription
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.

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

Data

It will hold the Resource information, this field will come in the request that returns a single element.

Items

It will hold an Array of Resources, this field will come in the request that returns multiple elements.