-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
2 changed files
with
233 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,6 +2,239 @@ | |
| fr: | ||
| api_particulier: | ||
| documentation_pages: | ||
| guide_migration: | ||
| title: Guide de migration 📋 | ||
| sections: | ||
| - anchor: 'introduction' | ||
| title: Introduction | ||
| content: |+ | ||
| **Ce guide liste les changements effectués entre la version 2 de l’API Particulier et la version 3, et vous livre les éléments nécessaires pour effectuer la migration**. | ||
| Les évolutions présentées ici ont été guidées par trois objectifs : | ||
| - assurer une meilleure sécurité de la donnée des fournisseurs ; | ||
| - normaliser les formats pour faciliter la compréhension et l’industrialisation ; | ||
| - clarifier la documentation et simplifier les routes des différentes modalités d'appel ; | ||
| - clarifier, documenter les réponses et les rendre actionnables par vos logiciels ; | ||
| - faire converger l'architecture technique de l'API Particulier avec celle de l'API Entreprise. | ||
| {:.fr-highlight.fr} | ||
| > **Votre jeton d'accès reste identique 🔑** | ||
| > Pour accéder à la version 3 de l'API Particulier, utilisez le même token qu'en V.2. En effet, tant que votre jeton est valide, il est inutile de refaire une demande d'accès car la migration vers la V.3 ne change pas les droits que vous avez déjà obtenu. | ||
| - anchor: 'evolutions-generales' | ||
| title: Évolutions générales | ||
| subsections: | ||
| - title: 1. Jeton d'accès à paramétrer dans le header | ||
| anchor: 'jeton-daccès-à-paramétrer-dans-le-header-' | ||
| content: |+ | ||
| **🚀 Avec la V.3 :** Le jeton est à paramétrer uniquement dans le header de l’appel. | ||
| {:.fr-highlight.fr-highlight--example} | ||
| > **Avant** : Le jeton JWT pouvait être un paramètre de l’URL d’appel (query parameter). | ||
| **🤔 Pourquoi ?** | ||
| - Respecter les standards de sécurité ; | ||
| - Garantir que le token ne sera pas utilisé dans un navigateur. | ||
| **🧰 Comment ?** | ||
| Utilisez un client REST API pour tester les API pendant le développement. | ||
| Des clients sont disponibles gratuitement. API Particulier utilise pour ses propres tests le client Insomnia. Le plus connu sur le marché est Postman. | ||
| Une fois le client installé, vous pouvez directement intégrer notre fichier [Swagger/OpenAPI](<%= developers_openapi_path %>){:target="_blank"} dedans. | ||
| - title: 2. Votre numéro de SIRET obligatoire dans le "recipient" | ||
| anchor: 'votre-numéro-de-siret-obligatoire-dans-le-recipient' | ||
| content: |+ | ||
| **🚀 Avec la V.3 :** Le paramètre obligatoire `recipient` de l’URL d’appel devra obligatoirement être complété par votre numéro de SIRET. | ||
| {:.fr-highlight.fr-highlight--example} | ||
| > **Avant** : Ce paramètre obligatoire n’était pas contraint en termes de syntaxe. | ||
| **🤔 Pourquoi ?** | ||
| - Pour garantir la traçabilité de l’appel jusqu’au bénéficiaire ayant obtenu l’habilitation à appeler l’API Particulier et respecter nos engagements auprès des fournisseurs de données ; | ||
| - Nous avions trop d’utilisateurs inscrivant le numéro de SIRET ou RNA de l’entreprise/association recherchée. | ||
| {:.fr-highlight.fr-highlight--caution} | ||
| > **⚠️ Cas particulier**, _vous êtes un éditeur ?_ | ||
| > Ce n’est pas votre numéro de SIRET mais celui de votre client public qu’il s’agira de renseigner. API Particulier doit pouvoir tracer pour quelle entité publique l'appel a été passé. | ||
| Pour en savoir plus sur les paramètres obligatoires d'appel, consultez les [spécifications techniques](<%= developers_path(anchor: 'renseigner-les-paramètres-dappel-et-de-traçabilité') %>). | ||
| - title: 3. Codes erreurs spécifiques à chaque situation, actionnables et documentés | ||
| anchor: 'codes-erreurs-spécifiques-à-chaque-situation-actionnables-et-documentés' | ||
| content: |+ | ||
| **🚀 Avec la V.3 :** Tous les codes erreur HTTPS sont accompagnés de codes plus précis, spécifiques à chaque situation d’erreur. Une explication en toutes lettres est également donnée dans la payload. Enfin, dans certains cas, une métadonnée actionnable est disponible. | ||
| Dans l’exemple ci-dessous, la clé `retry_in` permet de relancer un appel après le nombre de secondes indiquées. | ||
| ###### Exemple de _payload_ d’un code HTTP 502 : | ||
| ``` | ||
| { | ||
| "errors": [ | ||
| { | ||
| "code": "04501", | ||
| "title": "Analyse de la situation du compte en cours", | ||
| "detail": "La situation de l'entreprise requiert une | ||
| analyse manuelle d'un agent de l'URSSAF. | ||
| Une demande d'analyse vient d'être envoyée, | ||
| cela prend au maximum 2 jours.", | ||
| "meta": { | ||
| "provider": "ACOSS", | ||
| "retry_in": 172800 | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
| {:.fr-highlight.fr-highlight--example} | ||
| > Avant : Seul le code HTTP standard vous était fourni. Il pouvait correspondre à de nombreuses situations. | ||
| > ###### Exemple de payload d’un code HTTP 502 : | ||
| > ``` | ||
| > { | ||
| > "errors": [ | ||
| > "L'ACOSS ne peut répondre à votre requête, réessayez ultérieurement (erreur: Analyse de la situation du compte en cours)" | ||
| > ] | ||
| > } | ||
| > ``` | ||
| **🤔 Pourquoi ?** | ||
| - Pour préciser la nature de l’erreur et vous aider à la comprendre ; | ||
| - Pour vous permettre d’actionner automatiquement l’erreur en utilisant le code. | ||
| **🧰 Comment ?** | ||
| Utiliser les libellés pour comprendre l’erreur rencontrée, voire automatiser votre logiciel en fonction du code. | ||
| La liste de tous les codes erreurs spécifiques (environ 80) est disponible dans le [Swagger](<%= developers_openapi_path %>){:target="_blank"}. La gestion des erreurs et l'explication des codes retours est détaillée dans la [documentation technique générale](<%= developers_path(anchor: 'code-https-et-gestion-des-erreurs') %>){:target="_blank"}. | ||
| - title: 4. Volumétrie indiquée dans le header et actionnable | ||
| anchor: 'volumétrie-indiquée-dans-le-header-et-actionnable' | ||
| content: |+ | ||
| La gestion de la volumétrie est maintenue identique à la dernière évolution de la V.2 et expliquée dans cette [documentation](<%= developers_path(anchor: 'volumétrie') %>) | ||
| - title: 5. Gestion des évolutions futures | ||
| anchor: 'gestion-des-évolutions-futures' | ||
| content: |+ | ||
| **🚀 Avec la V.3 :** Toutes les API pourront évoluer indépendamment les unes des autres. Les anciennes versions resteront disponibles si le fournisseur de la donnée continue de nous transmettre les informations. Le numéro de version devient donc un paramètre de l’appel et non plus une valeur fixe pour toutes les API. | ||
| 📩 Une infolettre annoncera systématiquement les nouvelles évolutions. | ||
| {:.fr-highlight.fr-highlight--example} | ||
| > **Avant** : L’évolution d’un endpoint exigeait la montée en version de toute l’API. | ||
| **🤔 Pourquoi ?** | ||
| - Permettre l’ajout de nouvelles informations sans forcer les fournisseurs de service à monter de version ; | ||
| - Continuer de garantir la continuité des API dans le temps. | ||
| **🧰 Comment ?** | ||
| Renseigner directement le numéro de la version voulue dans l’URL, au même endroit qu’avant, par exemple : | ||
| ``` | ||
| https://particulier.api.gouv.fr/v3/mesri/statut_etudiant/identite | ||
| ``` | ||
| - title: 6. Une route spécifique pour chaque modalité d'appel | ||
| anchor: 'une-route-specifique-pour-chaque-modalite-d-appel' | ||
| content: |+ | ||
| **🚀 Avec la V.3 :** Chaque modalité d'appel d'une API a son propre endpoint | ||
| Désormais avec la V.3. chaque modalité d'appel a son propre endpoint, matérialisé ainsi dans l'URL d'appel : | ||
| - `/identite`, pour les appels avec les paramètres de l'identité pivot du particulier ; | ||
| - `/france_connect`, pour les appels avec FranceConnect ; | ||
| - `/identifiant`, pour les appels avec un numéro unique spécifique à l'API. | ||
| {:.fr-highlight.fr-highlight--example} | ||
| > **Avant** : Dans la V.2., une seule route existait par API, ce qui signifiait que les différentes modalités d'appel étaient toutes documentées au même endroit, entrainant plusieurs difficultés, dont notamment le fait de ne pas pouvoir rendre obligatoires certains paramètre pourtant obligatoires dans les faits. | ||
| **🤔 Pourquoi ?** | ||
| - Clarifier la documentation des paramètres d'appel ; | ||
| - Identifier précisémement les paramètres obligatoires ; | ||
| - Rendre actionnable le swagger et le fichier OpenAPI. | ||
| **🧰 Comment ?** | ||
| Utiliser [le swagger](<%= developers_openapi_path %>){:target="_blank"}. | ||
| - title: 7. Des payloads permettant de repérer plus facilement les scopes (droits d'accès) | ||
| anchor: 'payloads-permettant-de-reperer-les-scopes' | ||
| content: |+ | ||
| **🚀 Avec la V.3 :** Les scopes sont repérables plus facilement car ils sont incarnés par une seule clé (qui peut être une clé parente) et qui dans la mesure du possible se trouve à la racine du tableau `"data"`. Ce changement est particulièrement visible sur l'API statut étudiant boursier : | ||
| ###### Exemple avec la payload V.3. de l'API Étudiant boursier : | ||
| Dans cette payload, les différents scopes pour lesquels vous pouvez demander une habilitation sont très visibles : | ||
| ``` | ||
| { | ||
| "data": { | ||
| "identite": { ## Scope "identité" | ||
| "nom": "Moustaki", | ||
| "prenoms": ["Georges", "Claude"], | ||
| "date_naissance": "1992-11-29", | ||
| "nom_commune_naissance": "Poitiers", | ||
| "sexe": "M" | ||
| }, | ||
| "est_boursier": true, ## Scope "statut" | ||
| "periode_versement_bourse": { ## Scope "Période de versement" | ||
| "date_rentree": "2019-09-01", | ||
| "duree": 12 | ||
| }, | ||
| "etablissement_etudes": { ## Scope "Établissement et ville d'études" | ||
| "nom_commune": "Brest", | ||
| "nom_etablissement": "Carnot" | ||
| }, | ||
| "echelon_bourse": "6", ## Scope "Échelon de la bourse" | ||
| "email": "[email protected]", ## Scope "E-mail | ||
| "statut_bourse": { ## Scope "Statut définitif de la bourse" | ||
| "code": 0, | ||
| "libelle": "définitif" | ||
| } | ||
| }, | ||
| "links": {}, | ||
| "meta": {} | ||
| } | ||
| ``` | ||
| {:.fr-highlight.fr-highlight--example} | ||
| > Avant : Les droits d'accès pouvait couvrir une ou plusieurs clés dans la payload, il n'y avait pas de règles. Dans certains cas, un scope pouvait même indiquer un périmètre de particuliers concernés. | ||
| > ###### Exemple avec la payload V.2. de l'API Étudiant boursier : | ||
| > ``` | ||
| > { | ||
| > "data": { | ||
| > "nom": "Moustaki", | ||
| > "prenom": "Georges", | ||
| > "prenom2": "Claude", | ||
| > "date_naissance": "1992-11-29", | ||
| > "lieu_naissance": "Poitiers", | ||
| > "sexe": "M", | ||
| > "boursier": true, | ||
| > "echelon_bourse": "6", | ||
| > "email": "[email protected]", | ||
| > "date_de_rentree": "2019-09-01", | ||
| > "duree_versement": 12, | ||
| > "statut": 0, | ||
| > "statut_libelle": "définitif", | ||
| > "ville_etudes": "Brest", | ||
| > "etablissement": "Carnot" | ||
| > }, | ||
| > "links": {}, | ||
| > "meta": {} | ||
| > } | ||
| > ``` | ||
| **🤔 Pourquoi ?** | ||
| Clarifier quelles informations sont disponibles pour chaque scope. | ||
| - title: 8. Les données des payloads, qualifiées et uniformisées d'un point de vue métier | ||
| anchor: 'donnee-qualifiee-et-uniformisee-metier' | ||
| content: |+ | ||
| **🚀 Avec la V.3 :** Nous avons profité de la refonte technique pour uniformiser la façon de traiter la donnée entre les API et compléter significativement les documentations. Ces évolutions concernent plusieurs aspects : | ||
| - **Normaliser et préciser les clés de certains champs qui définissent le même type d'information**. Ainsi quelques règles sont maintenant largement utilisées sur toutes les API, par exemple : | ||
| - le statut (étudiant, bénéficaire d'une prestation, etc.) est désormais toujours nommé par une clé préfixée par `est_...`, comme par exemple `est_boursier` ou `est_beneficiaire` ; | ||
| - les dates de début et de fin de droit auront les clés `date_debut_droit` / `date_fin_droit` ; | ||
| - les clés se veulent les plus précises possibles, par exemple, dans l'API étudiant, : la clé `code_commune` en V.2. devient `code_cog_insee_commune` en V.3. pour éviter toute confusion avec le code postal. | ||
| - **Expliciter l'origine des diverses données d'identité transmises dans les payloads** et préciser si la donnée a été consolidée et comment. Par exemple : au travers d'un recoupement avec une pièce d'identité ou bien avec un répertoire ; | ||
| - Uniformiser le style des clés pour faciliter votre lecture de la documentation. Le format choisi est désormais en XXXX, c'est-à-dire que les mots sont séparés par des _, par exemple `code_cog_insee_commune`. | ||
| **🤔 Pourquoi ?** | ||
| - Simplifier la compréhension et la lecture des données transmises ; | ||
| - Faciliter l'intégration de l'API. | ||
| developers: | ||
| title: Espace développeurs 🛠 | ||
| sections: | ||
|
|
||