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.

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.