Resultsets

This document covers information about result sets and how they are structured

πŸ‘

TL;DR

@TODO RESULTSETS

When requesting data from an endpoint of the wunderbon API it may respond with a Resultset when successful or an Error in case something went wrong. Let us have a look at the first case: The Resultset is the data the wunderbon API returns on your request. All API access is over HTTPS, and accessed from https://api.wunderbon.io. All data is sent and received as JSON.

6464

Resultsets

Foo

πŸ‘

Resultset and Collections

The Resultset of the wunderbon API is standardized. The wunderbon API makes use of default parameters for ordering and pagination. This document gives you a detailed overview on that.

A request to an endpoint will either return a Resultset or an Error. The data node of the Resultset is either a single entity or a collection of entities. This depends on the endpoint queried.

Find more information on the concrete results of endpoints in its documentation.

Schemas & Models

All data structures are based on JSON-Schemas. So validation is very handy. The data structures returned by the endpoints queried will match exactly your expectation as long as you stick on the API Version. If the behavior is about to change you will find information about that in the changelog.

πŸ‘

JSON-Schemas

All data is sent and received as JSON and so wunderbon decided to take JSON-Schemas into account for validating data structures. This is very handy and enables us to provide you those Schemas as Open Source software for use in your software. See Git-Repository json-schemas or npm package @wunderbon/json-schemas for more details for more details.

NPMNPM

Example

Let us now have a look at an example:

https://playground-api.wunderbon.io/v1/users/3e8898c4-c86d-47fd-b5f0-7f18123ec02f
accept: application/vnd.api+json
authorization: Api-Key SECRET-API-KEY
access-control-allow-credentials: true
access-control-allow-headers: X-Requested-With,Content-Type,Accept,Origin
access-control-allow-methods: *
access-control-allow-origin: *
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4523
X-RateLimit-Window: 3600
X-RateLimit-Reset: 1372700873
connection: keep-alive
content-type: application/json
date: Fri, 06 Mar 2020 11:21:56 GMT
server: cloudflare
transfer-encoding: chunked
vary: Origin
{
  "meta": {
    "success": true
  },
  "data": {
    "type": "Users",
    "id": "3e8898c4-c86d-47fd-b5f0-7f18123ec02f",
    "attributes": {
      "email": "[email protected]",
      "salutation": "Mrs.",
      "firstName": "Jane",
      "lastName": "Doe"
    }
  }
}

Control Parameters

Whenever you request data from a wunderbon API endpoint that returns a collection of entities, the returned data is modified using defaults. These defaults include the limit of results per page, the attribute the results are ordered by, and den page offset to start at.

The following defaults will apply to that filters:

πŸ“˜

Default Control Parameters

  • ordered by created Datetime field,
  • order direction ASC,
  • starting at offset 0
  • limited to 100 entities per page,

You can modify the result by making use of the following parameters to modify the output of a collection:

ParameterShortDescription
order_byOName of the field to order resultset by (e.g. Name, defaults to created Datetime).
order_directionDName of the field to control order direction (e.g. ASC or DESC, defaults to ASC)
offsetPOffset to start (e.g. 200, defaults to 0).
limitCNumber of results to request from result set ( e.g. 50, defaults to 100).
/users?offset=100&limit=100&order_by=id&order_direction=DESC

The example above reads as follows:

Fetch users collection, Start at entity: 100, results per page: 100 and order by: id in descending order.


What’s Next

Continue with our guided tour. Now, we would like to tell you more about Timezones and how we ensure that all data is created with the right timestamp no matter from which timezone it arrives ...