Documentation API Yoplanning

API REST yoplanning.pro

Introduction

L'API Yoplanning est structurée autour du principe REST. Notre API propose des URL orientées ressource prévisibles et utilise les codes de réponse HTTP pour indiquer les erreurs et le succès des appels API. Nous exploitons les fonctionnalités HTTP intégrées, telles que l'authentification HTTP et les verbes HTTP, qui sont compris par les clients HTTP standards. Toutes les méthodes de notre API retournent du JSON.

Authentification

Pour commencer, vous devez demander un jeton API pour pouvoir interroger l'API Yoplanning. Pour ce faire, veuillez nous contacter. Une fois que vous avez votre jeton en main, vous pouvez commencer à travailler avec l'API. Toutes les méthodes de l'API nécessitent une authentification.

Nous utilisons un système d'authentification standard basé sur des jetons. Pour vous authentifier, il suffit de fournir votre jeton API dans l'en-tête de chaque requête comme suit : Authorization: Token 4804c2cb4d87a13146d4de029f407c82149f2ada. Attention : l'espace entre "Token" et le jeton est important.

Voici un exemple complet utilisant 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'

Si vous ne fournissez pas de jeton ou si le jeton est invalide, l'API répondra avec un code HTTP 401 (Non autorisé) et vous donnera un champ "détails" dans le JSON de réponse pour vous aider à comprendre le problème.

Permissions

Lorsque vous avez demandé votre jeton API, des permissions spécifiques vous ont été accordées sur un certain ensemble de team. Cela signifie que vous ne pouvez probablement pas utiliser toutes les méthodes de l'API. Si vous appelez l'API Yoplanning sans permissions, l'API répondra avec un code HTTP 403 (Interdit).

Limitation des requêtes

Pour des raisons de sécurité, le nombre de requêtes que vous pouvez effectuer est limité. Vous pouvez envoyer jusqu'à 5 requêtes par seconde et 1000 requêtes par jour. Au-delà de ce taux, le serveur répondra avec un code HTTP 429 (Trop de requêtes).

Vue d'ensemble

Team

La team est le concept le plus fondamental dans Yoplanning (qui est un outil collaboratif). Presque toutes les méthodes prennent un paramètre teamId dans l'URL, ce qui signifie que toutes les actions sont relatives à une Team.

UUID

De nombreuses méthodes nécessitent un paramètre "pk" dans l'URL. Il s'agit de l'identifiant unique pour la ressource que vous essayez de récupérer/créer/mettre à jour/supprimer. Yoplanning utilise UUID (version 4) comme identifiant unique pour toutes les ressources.

Points de terminaison et verbes HTTP

Pour de nombreuses ressources, 2 points de terminaison sont disponibles :

• Un pour accéder à une instance spécifique. L'URL se termine généralement par <pk>.

• Un pour accéder au gestionnaire d'instances : Ces points de terminaison utilisent les verbes HTTP suivants :

  • GET : obtenir une liste de toutes les ressources (voir Pagination)

  • POST : créer une nouvelle ressource (L'identifiant sera généré par le serveur)

Pagination

Pour toutes les méthodes de l'API qui fournissent une grande liste de ressources, la pagination est utilisée. Cela signifie que tous les résultats ne seront pas donnés dans une seule requête. Vous devrez effectuer plusieurs requêtes pour obtenir la liste complète des ressources.

Filtres

Pour certains points de terminaison, vous pouvez filtrer les résultats en ajoutant des paramètres de requête à la demande.

Champs extensibles

Pour certains points de terminaison, l'objet ressource contient des ressources imbriquées. Pour éviter d'envoyer plus de requêtes, vous pouvez utiliser le mécanisme d'extension de l