API Référence
Introduction
L'API La Cagnotte des Proches est organisée autour de REST. Notre API possède des URL orientées ressources prévisibles, accepte les corps de requête x-www-form-urlencoded et form-data, retourne des réponses encodées en JSON et utilise des codes de réponse HTTP standard, ainsi que l'authentification et les verbes HTTP standards.
À ce jour, L'APIv2 n'est ouverte qu'aux partenaires identifiés par l'équipe de La Cagnotte des Proches.
Se rapprocher de La Cagnotte des Proches pour toute utilisation.
Authentification
La Cagnotte des Proches utilise des clés d'API pour authentifier les requêtes.
Les clés d'API sont gérées par La Cagnotte des Proches et sont associées à un compte utilisateur enregistré.
Pour obtenir les clés d'API, vous devez en faire la demande à La Cagnotte des Proches.
Votre compte doit être partenaire.
Veillez également à fournir vos noms de domaines qui seront utilisés lors de vos requêtes.
Ce jeu de clés est donc personnel. Il peut comporter des privilèges propres à certaines ressources.
Veillez donc à le garder sécurisé ! Ne le partagez pas.
Toutes les demandes d'API doivent être effectuées via HTTPS. Les appels effectués via HTTP non sécurisé échoueront. Les demandes d'API sans authentification échoueront également.
API Keys
La Cagnotte des Proches authentifie les requêtes API en vérifiant les clés d'API de votre compte. Si une requête ne comporte pas une clé d'API valide, la requête renverra une erreur HTTP 401 UNAUTHORIZED.
Secret et Publishable keys
Un compte dispose de deux clés d'API :
secret key : Utiliser cette clé pour authentifier les requêtes serveurs.
publishable key : Utiliser cette clé pour authentifier les requêtes depuis un client web (client-side code).
Se référer à la description de la dite ressources pour connaitre quelle clé utiliser.
Sécurité
Nous vous demandons de bien protéger votre clé secrète.
- Ne partagez pas votre clé secrète, elle est à usage unique.
- Ne sauvegardez pas la clé secrète dans le code source.
- Ne sauvegardez pas la clé dans un système de versionning (ex : Github).
Lors de la création du jeu de clé d'API, il vous sera demandé de fournir une liste comportant :
- les noms de domaine
- les adresses IP
Vos clés d'API seront restrictifs aux noms de domaines et IP fournis.
Si votre clé secrète a été compromise, nous vous demandons d'informer immédiatement La Cagnotte des Proches. De nouvelle clés seront générées, révoquant également les anciennes.
Erreurs
Les erreurs retournées par l'API de La Cagnotte des Proches utilisent les codes de réponses HTTP habituels. Les codes 2xx indiquent un succès. Les codes 4xx indiquent une erreur causée par les informations fournies (ex. un paramètre requis a été omis etc.). Les codes 5xx indiquent une erreur avec les serveurs de La Cagnotte des Proches.
Les erreurs 400, 401, 403, 422 incluent dans la réponse un champ detail qui explique l'erreur.
champs
detail
La description de l'erreur.
| 200 | OK | Tout fonctionne |
| 401 | Unauthorized | Le token est invalide |
| 403 | Forbidden | Le token n'a pas les permissions |
| 422 | Unprocessable entity | La requête est invalide (données invalides) |
| 429 | Too many request | Trop de requête au même moment. |
| 5xx | Server errors | Quelque chose s'est mal passé du côté serveur La Cagnotte des Proches |
Pagination
Les requêtes GET qui liste un ensemble de ressources prennent en charge la pagination.
Comme par exemple le listing des cagnottes. Les paramètres en commun sont page, per_page.
paramètres
page (facultatif, par défaut à 1)
Le numéro de page.
per_page (facultatif, par défaut à 1)
Le nombre d'élément par page.
réponse liste format
page entier
Le numéro de page.
per_page entier
Le nombre d'élément par page.
total entier
Le nombre total d'élément.
items tableau
Un tableau contenant les éléments de réponse, paginés par tous les paramètres de requête.
{
"page": 1,
"per_page": 20,
"total": 1,
"items": [{...}]
}