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
.
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 anError
. Thedata
node of theResultset
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 takeJSON-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.
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:
Parameter | Short | Description |
---|---|---|
order_by | O | Name of the field to order resultset by (e.g. Name, defaults to created Datetime). |
order_direction | D | Name of the field to control order direction (e.g. ASC or DESC, defaults to ASC) |
offset | P | Offset to start (e.g. 200, defaults to 0). |
limit | C | Number 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
andorder by: id
indescending order
.
Updated over 2 years ago
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 ...