Yoplanning API Documentation
Introduction
The Yoplanning API is structured around the REST principle. Our API provides predictable resource-oriented URLs and uses HTTP response codes to indicate errors and success of API calls. We leverage built-in HTTP features, such as HTTP authentication and HTTP verbs, which are understood by standard HTTP clients. All methods in our API return JSON.
Authentication
To get started, you need to request an API token to be able to query the Yoplanning API. To do this, please contact us. Once you have your token in hand, you can start working with the API. All API methods require authentication.
We use a standard token-based authentication system. To authenticate, simply provide your API token in the header of each request as follows: Authorization: Token 4804c2cb4d87a13146d4de029f407c82149f2ada. Warning: the space between "Token" and the token is important.
Here is a complete example using curl:
If you do not provide a token or the token is invalid, the API will respond with an HTTP 401 (Unauthorized) code and give you a "details" field in the response JSON to help you understand the problem.
Permissions
When you requested your API token, you were granted specific permissions on a certain set of teams. This means you probably can't use every method in the API. If you call the Yoplanning API without permissions, the API will respond with an HTTP code 403 (Forbidden).
Limiting queries
For security reasons, the number of requests you can make is limited. You can send up to 5 requests per second and 1000 requests per day. Beyond this rate, the server will respond with an HTTP code 429 (Too many requests).
Overview
Team
The team is the most fundamental concept in Yoplanning (which is a collaborative tool). Almost all methods take a teamId parameter in the URL, which means that all actions are relative to a Team.
UUID
Many methods require a "pk" parameter in the URL. This is the unique identifier for the resource you are trying to retrieve/create/update/delete. Yoplanning uses UUID (version 4) as a unique identifier for all resources.
HTTP endpoints and verbs
For many resources, 2 endpoints are available:
One to access a specific instance. The URL usually ends with
<pk>.One to access the instance manager: These endpoints use the following HTTP verbs:
GET: get a list of all resources (see Pagination)
POST: create a new resource (The identifier will be generated by the server)
Paging
For all API methods that provide a large list of resources, paging is used. This means that not all results will be given in a single query. You will need to perform multiple queries to get the full list of resources.
Filters
For some endpoints, you can filter results by adding query parameters to the request.
Expandable fields
For some endpoints, the resource object contains nested resources. To avoid sending more requests, you can use the extension mechanism
Last updated
