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
timestampCall’s time mark
transactionIdCall’s transaction ID, this will help our teams to locate issues faster if arose
explainCould 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
offsetHow many items we are skipping in this call, this establish the initial point.
limitHow many items per page we want to fetch in this call.
nextWhich is the next item to be queried to keep continuity when passing pages. This is meant to be used with offset.
pageThe current page indicator, this is useful for clients and help preventing them to.
pagesTotal pages, this value its relative and will depends on the total items in the collection and the limit used on the call.
totalTotal 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
reasonThe failure main reason as a descriptive text.
detailsA key -> value map to add additional information about the error.