Yoplanning API Documentation

Introduction

The Yoplanning API is structured around the REST principle. Our API offers predictable, resource-oriented URLs and uses HTTP response codes to indicate errors and successes 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 begin, you need to request an API token to query the Yoplanning API. To do so, please contact us. Once you have your token, 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. Note: the space between "Token" and the token name is important.

Here is a complete example using curl:

curl -H "Content-Type: application/json" https://yoplanning.pro/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/clients/8d23503e-041e-4180-98d1-641183bc5ead -H 'Authorization: Token 4804c2cb4d87a13146d4de029f407c82149f2ada'

If you do not provide a token or if 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 likely cannot use all API methods. If you call the Yoplanning API without permissions, the API will respond with an HTTP 403 (Forbidden) error.

Request limitation

For security reasons, the number of requests you can make is limited. The applicable limits are specified in the API specification, section "Throttling": https://yoplanning.pro/api/v3.1/swagger/. Beyond these limits, the API will respond with an HTTP 429 code (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, meaning that all actions are related 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, or delete. Yoplanning uses UUID (version 4) as the unique identifier for all resources.

HTTP Endpoints and Verbs

For many resources, two 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, pagination is used. This means that not all results will be returned in a single request. You will need to make multiple requests to obtain the complete list of resources.

Filters

For some endpoints, you can filter the results by adding query parameters to the request.

Extensible fields

For some endpoints, the resource object contains nested resources. To avoid sending more requests, you can use the field expansion mechanism: add the expand query parameter to the URL to directly include a nested resource in the response. For example: ?expand=product. You can request multiple fields by separating them with commas, and deeply nested fields using dot notation, for example ?expand=session_group.product.