Spécifications techniques de chacune des API :
- Paramètres d’appels
- Détail de la réponse JSON
- Codes erreurs
Voici la liste des fondamentaux techniques à mettre en place pour le bon fonctionnement de l’API Particulier :
💡 Pour mieux comprendre l’API Particulier avant de demander un accès, vous pouvez utiliser notre environnement de test.
Les limites de volumétrie sur API Particulier se décomposent en deux règles principales :
Un plafond général par IP de 1000 requêtes/minute ;
Une volumétrie par jeton : 20 requêtes/secondes.
Dans toutes les réponses de nos API, le header vous transmet des informations sur la volumétrie :
Champs du header | Signification | Format |
---|---|---|
RateLimit-Limit |
La limite concernant l’endpoint appelé, soit le nombre de requête/minute. | Nombre |
RateLimit-Remaining |
Le nombre d’appels restants durant la période courante d’une minute. | Nombre |
RateLimit-Reset |
La fin de la période courante. | Timestamp |
Exemple :
Considérons un endpoint ayant une limite de 50 appels /minute.
Vous faîtes un premier appel à 10h00 pile, et effectuez un second appel 20 secondes plus tard, puis un troisième 10 secondes plus tard, vous aurez les valeurs suivantes :
RateLimit-Limit
: 50 ;RateLimit-Remaining
: 47 (50 moins les 3 appels effectués) ;RateLimit-Reset
: [Timestamp correspondant au jour présent à 10h01]. Le premier appel initialise le compteur (à 10h00 pile), la période se termine 1min plus tard.Vous pouvez donc jusqu’à 10h01 pile effectuer 47 appels, le compteur sera réinitialisé à 50 à ce moment-là.
Si vous dépassez le nombre d’appels autorisés (RateLimit-Remaining = 0
), le serveur répondra avec le status 429
sur tous les appels suivants dans la même période.
Le header associé à ce code erreur 429
sera accompagné :
Champs du header | Signification | Format |
---|---|---|
RateLimit-Limit |
La limite concernant l’endpoint appelé, soit le nombre de requête/minute. | Nombre |
RateLimit-Remaining |
Le nombre d’appels restants durant la période courante d’une minute. | Nombre |
RateLimit-Reset |
La fin de la période courante. | Timestamp |
Uniquement pour le header associé au code erreur 429 Retry-after |
Décompte du nombre de secondes restantes avant la prochaine période | Secondes |
Vous pouvez donc utiliser les champs du header pour optimiser votre consommation de l’API Particulier.
En cas de non prise en compte des codes erreurs 429
ou en cas de dépassement de la limite de volumétrie globale, votre IP sera temporairement bannie de nos serveurs pour une durée fixe et non révocable de 12h. Si vous avez plusieurs jetons, tous seront donc bloqués pendant ce laps de temps.
Les appels depuis une IP bannie ne renvoient pas de codes HTTP, le serveur ne répond tout simplement pas.
ℹ️ Au bout de ces 12 heures, vos accès sont automatiquement rétablis ; il est donc inutile d’écrire au support.
Nous vous invitons à prendre les mesures nécessaires car le dépassement intervient généralement chez nos utilisateurs lorsque leur programme n’a pas été correctement configuré.
Pour les appels de traitement de masse, il est souhaitable que vous fassiez vos batchs automatiques la nuit ou durant les heures creuses afin de ne pas affecter la qualité du service pour le reste des usagers.
Le timeout est le temps d’attente maximal de réponse à une requête. Il vous permet de ne pas immobiliser votre logiciel en le laissant bloqué sur un appel sans réponse.
De façon générale, nous vous recommandons un timeout de 5 secondes.
De même, pour ne pas immobiliser nos serveurs, nous attendons les réponses de nos fournisseurs un maximum de 10 secondes avant de vous les retransmettre. Si ce délai d’attente est dépassé un code erreur HTTP 504
vous sera renvoyé.
API Particulier utilise DHIMYOTIS comme organisme de délivrance de ses certificats SSL principaux ainsi que Let’s Encrypt pour certains services secondaires.
Il est conseillé d’ajouter ces Autorités de Certifications (AC) à votre base de confiance si vous en avez une. Une solution idéale est d’utiliser un paquet d’autorités mises à jour automatiquement (Mozilla par exemple)
API Particulier utilise des certificats multi-domaines ; c’es-à-dire avec un “nom courant” (common name - CN) et plusieurs “noms alternatifs du sujet” (subject alternatives names - SAN), soyez certains que vos outils fonctionnent correctement avec.
Toutes les réponse de l’API Particulier sont envoyées avec un code HTTPS. Ces codes permettent de se renseigner sur le statut de l’appel, et sont harmonisés pour l’ensemble des API quelque soit le fournisseur de données.
Pour en savoir plus sur les codes HTTPS, cet article de Wikipedia constitue une bonne base explicative.
Code HTTPS | Signification |
---|---|
200 |
Tout va bien. |
Code HTTP | Signification |
---|---|
400 |
Mauvaise requête – La syntaxe de votre requête est erronée: les paramètres ne sont pas valides. |
401 |
Non autorisé – Votre token est invalide ou manquant. |
403 |
Interdit – Le serveur a compris votre requête mais refuse de l’exécuter car votre jeton ne vous donne pas accès à cette ressource. |
404 |
Non trouvé – La ressource demandée n’a pas été trouvée. |
Code HTTP | Signification |
---|---|
500 |
Erreur interne à API Particulier – Une erreur interne du serveur d’API Particulier est survenue. |
503 |
Service non disponible – Le service est temporairement indisponible ou en maintenance. |
504 |
Intermédiaire hors délai – Le(s) producteur(s) de données ont mis trop de temps à répondre. Notre temps d’attente, nous permettant de ne pas immobiliser le serveur sur un appel sans réponse, est fixé à 10 secondes et a été dépassé. |
Retrouvez tous les codes erreurs pour chaque endpoint dans notre swagger, partie “Response samples”.
La liste des codes spécifiques à chaque endpoint y est disponible.
Pour connaître la liste des APIs auxquelles vous avez le droit avec votre jeton d’accès, vous pouvez le vérifier avec l’API /api/introspect
.
Si vous gérez les tokens pour vos utilisateurs, vous pouvez aussi utiliser cette API pour vérifier les droits associés à leurs tokens.
https://particulier.api.gouv.fr/api/introspect?token=LeTokenATester
Le paramètre d’appel à renseigner est le token dont vous souhaitez connaître les droits.
Exemple de réponse JSON :
{ "_id": "48ed8e98-33e4-4b05-88fe-f933d1b421c4", "name": null, "scopes": [ "cnous_statut_boursier", [...] "cnaf_adresse" ] }
La réponse JSON renvoie la liste des API et champs autorisées. Retrouvez-leurs spécifications techniques dans le Swagger.
L’API Particulier est testable avec un jeton accessible à tous depuis notre environnement de staging. Ce bac à sable retourne des données fictives.
Pour utiliser l’environnement de test, plusieurs moyens sont possibles :
https://staging.particulier.api.gouv.fr
.Seule la personne ayant fait la demande d’habilitation a accès au token, au travers du compte utilisateur API Particulier.
Après avoir récupéré votre jeton, vous pouvez faire un premier appel de test.
Utilisez l’environnement de production documenté (Swagger), disponible sur api.gouv.fr.
Il permet, à l’aide d’un token d’authentification valide 🔑, d’effectuer directement depuis le navigateur des tests de l’API. Les données confidentielles restent bien protégées. Vous y trouverez aussi la spécification technique téléchargeable sous format YAML afin de pouvoir accélérer le développement de vos outils d’interfaçage avec API Particulier.
Chaque URL de requête est spécifiée dans le Swagger,
Placeholder