Prérequis techniques

Voici la liste des fondamentaux techniques à mettre en place pour le bon fonctionnement de l’API Particulier :

  • ☑️ Être en mesure de gérer le protocole HTTPS ;
  • ☑️ Avoir une version de langage récente. Si vous utilisez Java, une version >= 1.8 est nécessaire (pour la gestion des certificats de +1024 bit, du TLS 1.2 minimum et des suites cryptographiques - ciphers) ;
  • ☑️ S’assurer que nos Autorités de Certification (AC) pour les certificats SSL sont autorisées par vos systèmes ;
  • ☑️ L’API Particulier est uniquement accessible par internet. Si vous avez un pare-feu, il faut donc prévoir de whitelister l’adresse IP du service API Particulier ;
  • ☑️ Il est interdit d’interroger l’API Particulier depuis un site web en front-end, car le jeton d’accès serait alors divulgué. Il vous faut donc interroger nos API depuis une application en back-end. Nous n’autoriserons pas le CORS (CORS - Cross Origin Ressource Sharing) ;
  • ☑️ Prévoir non seulement les coûts de développement mais également les coûts de maintenance ;
  • ☑️ Être en capacité de gérer les mises à jour de l’API Particulier.


💡 Pour mieux comprendre l’API Particulier avant de demander un accès, vous pouvez utiliser notre environnement de test.

Spécifications générales 🎛

Respecter la volumétrie

Les plafonds

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.

Informations volumétrie dans le header

Pour toutes les réponses :

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à.

En cas de dépassement :

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é : 

  • des trois champs précédents ;
  • d’un champ supplémentaire indiquant le temps à attendre avant de pouvoir effectuer des nouveaux appels.
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.

Règles de bannissement en cas de surconsommation

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.

Configurer vos timeout

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é.

Autoriser nos Autorités de Certifications

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.

Gérer les erreurs - codes HTTPS

Un code standard HTTPS pour catégoriser le statut de l’appel

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.

En cas de succès, le code HTTP commence par 2 :
Code HTTPS Signification
200 Tout va bien.
En cas d’échec, si l’erreur vient de votre côté, le code HTTP commence par 4 :
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.
En cas d’échec, si l’erreur provient d’API Particulier ou bien des fournisseurs de données, le code HTTP commence par 5 :
Code HTTP Signification
500 Erreur interne à API Particulier – Une erreur interne du serveur d’API Particulier est survenue.
502 Erreur interne fournisseur – Une erreur interne du serveur du ou des fournisseurs est survenue. Consultez votre compte utilisateur, l’historique de l’incident devrait y être affiché ; ainsi que les actions à venir.
503 Service non disponible – Le service est temporairement indisponible ou en maintenance. Pour connaître l’historique de disponibilité et les incidents type de l’endpoint, vous pouvez consulter le catalogue de données.
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.

Renseigner les paramètres d'appel et de traçabilité

API Particulier vous permet d’accéder à des données protégées. C’est pourquoi, dans un objectif de traçabilité, nous vous demandons de renseigner dans chacune de vos requêtes, non seulement un jeton d’accès, mais aussi certaines informations qualifiant votre requête.

⚠️ Ces paramètres sont obligatoires. Les appels ne comportant pas ces paramètres sont rejetés, et un code erreur vous est renvoyé.

Pour chaque endpoint, nous précisons dans le swagger, rubrique “Query parameters” les paramètres obligatoires spécifiques, ci-dessous une explication détaillée des éléments à fournir pour chaque paramètre de traçabilité :

Paramètre Information à renseigner
&context=CadreDeLaRequête Le cadre de la requête

Par exemple : tarification transport, tarification cantine, portail famille, etc.
&recipient=BénéficaireDeL'Appel Le bénéficiaire de l’appel

Ce paramètre permet la traçabilité de l’appel et doit correspondre au SIRET de l’organisation publique habilitée à utiliser la donnée.

Si vous êtes une collectivité ou une administration, ce paramètre doit donc être votre numéro de SIRET. Si vous êtes un éditeur, il s’agit du SIRET de l’organisation publique cliente demandant la donnée.

Une vérification est effectuée par API Particulier pour refuser tout format qui ne serait pas un numéro de SIRET.
&object= RaisonDeL'AppelOuIdentifiant La raison de l’appel
ou l’identifiant de la procédure.

L’identifiant peut être interne à votre organisation ou bien un numéro ou nom de procédure ; l’essentiel est que celui-ci vous permette de tracer et de retrouver les informations relatives à l’appel. En effet, vous devez pouvoir justifier de la raison d’un appel auprès du fournisseur de données.
Description courte (< 50 caractères).

Surveiller l'état des fournisseurs

API Particulier met à disposition un ensemble de routes de “pings” permettant de récupérer l’état des services fournis par les différents fournisseurs de données.
L’ensemble des routes est disponible à l’adresse suivante: Routes de pings (format JSON).

Pour chacune de ces routes, l’équipe d’API Particulier effectue des vérifications spécifiques au fournisseur, permettant d’être au plus près de la réalité quand à la santé dudît fournisseur.
Chacune de ces routes renvoi un json sous le format suivant:

{
  "status": "ok",
  "last_update": "2023-11-03T12:24:07.185+01:00",
  "last_ok_status": "2023-11-03T12:24:07.185+01:00"
}

Avec:

  • status, string, qui peut avoir 3 valeurs: ok quand tout est OK, bad_gateway quand il y a un souci, unknown quand on ne peut pas déterminer le status ;
  • last_update, datetime, date de la dernière mise à jour: pour éviter de surcharger nos systèmes nous effectuons de la mise en cache sur les pings ;
  • last_ok_update, datetime, date de la dernière mise à jour en OK: permet de savoir depuis quand le service est en défaut.

A noter que le status http est à 200 pour ok et unknown, 502 pour bad_gateway : cela permet à nos systèmes de monitoring de ne pas lever d’alertes en cas de données insuffisantes (et ainsi éviter des potentiels faux positifs).

Nous vous conseillons de passer par ces routes de surveillances, et ceci pour plusieurs raisons:

  1. API Particulier s’occupe de la complexité vis-à-vis de la disponibilité de certains partenaires (limitation sur le nombre d’appels sur certains identifiants, échecs aléatoires etc..) ;
  2. Il n’y a pas de limitations sur ces routes
  3. L’implémentation est plus simple que d’utiliser les routes officieles
  4. Un bad gateway d’une route de ping a de forte chance d’être un vrai positif, contrairement à un échec sur les endpoints qui peut être dû à des erreurs réseaux/temporaires.

Retrouver les droits d'un jeton

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.

La requête HTTP :

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.

Kit de mise en production 🚀

Tester l'API en préproduction

L’API Particulier propose un environnement de test ou bac à sable pour vous permettre de tester le branchement de l’API avec votre système d’informations.

💡 L’environnement de test est une fonctionnalité à destination des usagers techniques. Si vous êtes un profil métier, veuillez vous référer aux fiches métier de chaque API disponibles depuis le catalogue.

Les informations essentielles du bac à sable :

  • Une URL : L’‘environnement de staging est appelable avec https://staging.particulier.api.gouv.fr.

  • Les jetons d’accès : Pour être fidèle au fonctionnement de l’API en production, cet environnement de test nécessite aussi un jeton d’accès, mais celui-ci, contrairement aux jetons de production, est public car la donnée renvoyée en bac à sable est fictive. Un jeton ayant tous les droits est accessible ici. Pour générer un jeton spécifique, veuillez vous référer à ce tutoriel.

  • Les paramètres d’appel : Chaque cas de test documente les paramètres d’appel nécessaires. Vous pouvez aussi tester l’API avec la modalité d’appel FranceConnect en utilisant de faux jetons FranceConnect fournis dans le staging.

  • Les données fictives de réponse : Les données retournées par cet environnement de test sont totalement fictives et disponibles depuis ce dépôt.

  • Pour rappel, le fichier OpenAPI est disponible depuis le swagger, avec le bouton “Download” situé en début de page.

Pour en savoir plus, veuillez consulter le README du dépôt Github.

Récupérer le jeton JWT 🔑

Seule la personne ayant fait la demande d’habilitation a accès au token, au travers du compte utilisateur API Particulier.

  • Si vous avez réalisé la demande d’habilitation, vous pouvez récupérer vos tokens ou jetons d’accès directement depuis votre compte.

Faire sa première requête

Utiliser l’environnement de production - Swagger

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.

Éléments constitutifs de la requête HTTP d’API Particulier

Chaque URL de requête est spécifiée dans le Swagger.

Constatez votre première trace d’appel depuis le compte utilisateur

Une fois que vous avez fait un premier appel, celui-ci est répertorié dans votre compte utilisateur, dans la page détaillée de l’habilitation concernée, au niveau du jeton. Un lien vous permet d’accéder aux statistiques.

Configurer le logiciel métier

Documentation en construction 🚧

Monitorer la disponibilité des API

Dès l’intégration d’API Particulier, prenez un temps pour vous assurer d’être informé de la disponibilité de nos API :

Incidents et maintenances 🚧

Que faire en cas de rupture de service ?

Le service ne répond plus ? consultez cette rubrique de notre FAQ.

Être informé des ruptures de service

  1. Abonnez-vous aux notifications par e-mail depuis notre page de statut.

  2. Ajoutez des routes de pings pour automatiser la surveillance des API par vous-même. Plutôt que de consulter ponctuellement notre page de statuts, vous pouvez vous branchez directement à nos routes afin d’avoir un suivi encore plus précis. Pour en savoir plus, consulter la rubrique surveiller l’état des fournisseurs ;

  3. Si vous rencontrez un problème et avez besoin d’échanger avec nous en transmettant des données sensibles, utilisez le formulaire de transfert d’informations sécurisées (Démarches simplifiées).
    Si vous n’avez pas de réponse sous 72h, n’hésitez pas à nous envoyer votre numéro de demande Démarches simplifiées à l’adresse api-particulier@api.gouv.fr.

Prolongation de la durée de vie du JWT 🔑

Pour comprendre comment prolonger votre jeton, consultez cette rubrique de notre FAQ.