-
Notifications
You must be signed in to change notification settings - Fork 13
Pagination
All API endpoints that return a collection of data may be used with the following query parameters unless otherwise specified.
&orderby=<fieldname>
Clients may use the orderby parameter with a value corresponding to the name of a sortable field belonging to the requested resource.
If this parameter is present, then the sort parameter MUST also be present.
The orderby parameter cannot be used without the sort parameter.
Explanation: See above.
The field <field> specified by the orderby parameter is not available for <resource type>.
Explanation: The client tried to sort by a field that does not exist on the object.
The field <field> specified by the orderby parameter cannot be used to sort the results.
Explanation: Not all fields support sorting. This could be because the type of the field in question is not inherently ordered, or simply because the server does not allow clients to sort by that particular field. Refer to a specific resource type's page in the documentation.
&sort=asc | &sort=desc
Clients may use the sort parameter to specify the sorting direction. This has a different meaning depending on the type of the field being used to sort the results. The following table summarizes the behavior of several data types when sorted in ascending order.
| Type | Behavior |
|---|---|
| numeric | low to high |
| date | earliest to latest |
| text | alphabetical |
Be aware that enumerated types will sort based on their internal representation and not their values! All enum types on this wiki will be listed in ascending sort order.
If this parameter is present, then the orderby parameter MUST also be present.
<dir> is not a valid sorting direction. Valid sorting directions are "asc" and "desc".
Explanation: The client provided a value other than asc or desc for the sort parameter.
The sort parameter cannot be used without the orderby parameter.
Explanation: See above.
&offset=<number>
Clients may use the offset parameter to have the server skip the first n data and omit them from the response. Specifying 0 for this field produces the same effect as not including it at all.
The value <value> supplied to the offset parameter is not an integer.
Explanation: Offsets must be whole number integers written in base ten in arabic numerals with no digit grouping.
The value <value> supplied to the offset parameter is too large.
Explanation: The number of records stored in a table in the database is limited by the size of the type used to key them. Typically, four- or eight-byte integer types are used for primary keys. If the offset is larger than the maximum number of entries capable of being stored in the table, an error is generated. This error can also be caused by the server not being able to store the value of the parameter in memory while parsing the request before the database being accessed.
The value supplied to the offset parameter is less than zero.
Explanation: Clients may not specify negative offsets.
&limit=<number>
Clients may specify a maximum number of results to return.
The value supplied to the limit parameter is not an integer.
Explanation: Offsets must be whole number integers written in base ten in arabic numerals with no digit grouping.
The value supplied to the offset parameter is less than zero.
Explanation: Clients may not specify negative values.
{
"total": <number>
}
The total field indicates the total number of entries in the database that match the specified query. Note that this number may not be the same as the number of queries returned. This field is not guaranteed to be present in any given response, but it should be present when the total number of results cannot be inferred. For example, the server may decide to omit this field if all available results are returned in the response. If a client wishes to simply get the number of entries in a given table without actually retrieving any, the client can specify limit=0
The server must apply the sort and orderby parameters before applying the offset and then finally the limit parameter. This means that even entries that aren't included in the response still have to be sorted, potentially making queries take a very long time on unindexed columns, even if only a few data are returned. Clients should not expect results to be returned in any particular order if they do not specify the sorting parameters, and the order may change even if the same query is repeated multiple times. Because of this, it is usually not a good idea to specify offset without sorting, as this could lead to duplicated or missing data. The server may limit the number of results returned even if the limit parameter is not specified. The server may return fewer results than limit, even when more entries exist. Any fields that support sorting must be able to be sorted in both ascending and descending order, and the two sort orders must be the exact inverses of each other.