Methods [1] are described individually grouped by logical function [2] and listed in the methods listing section.
Note: See resources for documentation on resource methods.
[1] Defined here.
[2] These groupings are subjective but hopefully intuitive.
Many methods share similar functionality, such as authentication and pagination, which this documentation terms a trait.
Having a particular trait indicates a method will behave in a certain way or provide certain functionality. Each method will document the traits it uses.
For example the authentication trait indicates a method will require a valid authentication token to be present in the request or an authentication failure will be returned.
The table below provides details of all possible traits a method may have, with a description, effect and a reference to additional documentation on each trait.
Note: Method descriptions will not include information pertaining to any traits it may use (unless a method uses or reacts to a trait in a non-standard way).
This means a method using the authentication trait, for example, will not include specifying an Authorization header in a request example as this is part of the authentication trait.
The following traits are provided by this API.
| Name | Description | Effect | Additional Documentation |
|---|---|---|---|
| Authentication | Checks for a valid authentication Token | A method can only be used if a valid authentication Token is provided | The Authentication document |
| Hard limit | Enforces an arbitrary limit to results | A method will drop any results that fall after a pre-set limit | The Hard limit section |
The hard limit trait is a temporary solution for dealing with methods that may return large numbers of results.
It is a very crude form of pagination, where the page size and page number are pre-set and cannot be changed by the end-user.
Where this trait is used only results up to the pre-set limit will be returned. Additional results will be dropped and cannot be accessed by the end-user.
The pre-set limit is set to 200.
Responses for methods using this trait will include additional meta-data and notices as required.
These keys are returned, in all responses, within the meta key of the top-level response object:
| Name | Property name | Data type | Description | Example |
|---|---|---|---|---|
| Limit | limit |
Integer | The pre-set limit | 200 |
This notice is returned where a response contains more results than the pre-set limit. The details object is designed to be machine readable.
For example:
{
"type": "search_hard_limit_triggered",
"details": {
"hard_limit": 200,
"results_returned": 200,
"results_possible": 1251,
"message": "This search returns over 200 results, however the first 200 results will be returned.A hard limit of 200 results for any request for performance reasons.It is not possible to request these additional results not returned by this response."
}
}
In this example the number of results is less than the pre-set limit
None.
{
"meta": {
"count": 47,
"limit": 200
}
}
In this example the number of results is more than the pre-set limit
None.
{
"meta": {
"count": 200,
"limit": 200
},
"notices": [
{
"type": "search_hard_limit_triggered",
"details": {
"hard_limit": 200,
"results_returned": 200,
"results_possible": 1251,
"message": "This search returns over 200 results, however the first 200 results will be returned.A hard limit of 200 results for any request for performance reasons.It is not possible to request these additional results not returned by this response."
}
]
}
This information may be out of date whilst this website is being redeveloped. Until then, if you have any problems using an API documented here, please contact the relevant project maintainer.