This page lists best practices and common concepts you can find in Giosg API's like pagination, ordering and date and time formats.¶
You should always define
Accept header with your requests to tell Giosg that you accept JSON formatted responses:
Alternatively, if you are unable to customize headers, you may add
format=json GET parameter.
Unless stated otherwise, all the resources in the system are identified with a Universally Unique Identifier (UUID). It is always represented as a string ID, in lower case and including dashes.
An example of a JSON response with a paginated collection
1 2 3 4 5 6 7 8 9 10 11
Some of the API endpoints return paginated collections. That means that for large collections of resources, not all resources are returned in a single response, but the response contains an URL that can be used to fetch the next chunk (page) of results.
Paginated collections are objects with the following attributes.
||string||Full URL for requesting the next page. This is
||string||Full URL for requesting the previous page. This is
||array of objects||The list containing the result resources for the current page. Each item is an object whose attributes depend on the returned resource type.|
Unless stated otherwise, the server only guarantees the order of the resources, but not the number of items returned per page. If you need a specific number of results, then you need to splice the returned list on the client.
If you need to load all resources using an endpoint returning paginated collections, then you need to check if the
next attribute is not
null, potentially load the next page and then repeat this until you have loaded and built the full collection of resources.
A paginated collection can usually be ordered by using an
The allowed sorting criteria depends on the endpoint, but the basic usage is always the same. You have an allowed set of sorting attributes, e.g.
created_at. You may then choose the primary sorting key and any secondary sorting keys with a comma-separated string, e.g.
Any sorting order is ascending by default, but may be reverted to descending order by prefixing with a minus (
-) character, e.g.
Unless stated otherwise, all the date/times returned by API endpoints are ISO-8601 strings with format
YYYY-MM-DDTHH:MM:SS.MSSZ, for example:
2015-08-31T16:32:17.879Z. Also, any date/time URL parameters or attributes send as a request payload accept this same format.
Unless stated otherwise, the times are expressed in UTC timezone!