Ce dépôt contient l'ensemble des données de tests pour les environnements de bac à sable d'API Entreprise (seulement pour la v3+) ( https://staging.entreprise.api.gouv.fr ) et d'API Particulier ( https://staging.particulier.api.gouv.fr ).
tl;dr: Trois commandes en console pour faire fonctionner l'environnement de test :
Récupération d'un jeton:
token=`curl https://raw.githubusercontent.com/etalab/siade_staging_data/develop/tokens/default`Test d'API Entreprise:
curl -H "Authorization: Bearer $token" \
-G -d 'recipient=10000001700010' -d 'context=Contexte+de+la+requ%C3%AAte' -d 'object=Objet+de+la+requ%C3%AAte' \
--url "https://staging.entreprise.api.gouv.fr/v3/urssaf/unites_legales/418166096/attestation_vigilance"Test d'API Particulier
curl -H "X-Api-Key: $token" \
-G -d 'codeInseeLieuDeNaissance=08480' -d 'codePaysLieuDeNaissance=99100' -d 'sexe=F' -d 'nomUsage=DUPONT' -d 'prenoms[]=JEANNE' -d 'prenoms[]=LAURE' -d 'anneeDateDeNaissance=1993' -d 'moisDateDeNaissance=8' \
--url "https://staging.particulier.api.gouv.fr/api/v2/complementaire-sante-solidaire"Les exemples sont dans les accordéons "Commande cURL" dans les dossiers de payloads
Chaque endpoint de l'API Entreprise ou de l'API Particulier, pour lesquels des cas de tests ont été proposés, possède un dossier dans payloads/, où sont regroupés ses cas de tests.
Le nom de ce dossier a la forme suivante : bouquetapi_version_endpointname.
Une table de correspondance url de l'endpoint <-> nom du dossier est disponible à la
racine du dossier payloads/ : README.md (généré
automatiquement par bin/generate_payload_readme.rb)
Pour API Entreprise :
Nom type du dossier d'un endpoint : api_entreprise_version_endpointname
Par exemple :
api_entreprise_v3_insee_unite_legale
➡️ Liens des dossiers d'endpoints de l'API Entreprise
Pour API Particulier :
Nom type du sous-dossier d'une payload : api_particulier_version_endpointname
Par exemple :
api_particulier_v2_dgfip_svair
➡️ Liens des dossiers d'endpoints de l'API Particulier
Chaque dossier possède un README.md ainsi que des fichiers YAML des différents cas de tests ayant un format du type suivant :
---
params:
first_name: 'John'
last_name: 'Doe'
status: 200
payload: |-
{
"status": "OK"
}Avec:
params, ensemble de clé valeur traduisant les paramètres qui déclenchent la réponse associée ;status, le status de la réponse HTTP associé ;payload, la payload renvoyée.
Toutes les autres clé potentiellements présentes dans la payload sont facultatives ou servent pour tout autre chose (affichage d'exemples sur les fiches métiers par exemple). Une liste (non-exhaustive) :
title, titre de la payload, utilisé pour l'exemple ;description, une description de la payload, utilisé pour l'exemple ;example, booléen, précise si la payload sera affichée sur dans les fiches métiers du catalogue ;
Pour déclencher l'exemple de payload de réponse précédent, exemple créé de toute pièce pour ce tutoriel, avec comme chemin tout aussi fictif v1/dgfip/impots, il faut effectuer l'appel suivant:
Pour API particulier :
curl -X GET \
-H 'X-Api-Key: TOKEN' \
-G -d 'first_name=John' -d 'last_name=Doe' \
https://staging.particulier.api.gouv.fr/v1/dgfip/impotsPour API Entreprise :
curl -X GET \
-H 'Authorization: Bearer TOKEN' \
-G -d 'first_name=John' -d 'last_name=Doe' \
https://staging.entreprise.api.gouv.fr/v1/dgfip/impotsLes routes sont listées à la racine du dossier payloads/
À noter qu'il est possible de mettre n'importe quel status (valide), hormis ceux associés aux paramètres invalides et au jeton invalide:
- Pour API Entreprise:
422et403; - Pour API Particulier:
400et401.
En effet, les paramètres d'entrées sont vérifiés directement par l'application, ce qui garantie un comportement iso avec la production.
Certains endpoints d'API Particulier sont FranceConnectés : cela implique que l'on peut passer un jeton FranceConnect à la place des paramètres classiques afin d'effectuer un appel auprès des fournisseurs de données. À l'aide du jeton FranceConnect, l'API effectue un appel auprès de FranceConnect pour récupérer des données de civilité (un exemple ici), données qui sont ensuite formatées pour effectuer un appel auprès du fournisseur de données correspondant.
Il est possible d'utiliser directement le service d'integration de FranceConnect et d'envoyer sur nos serveurs en staging un jeton FranceConnect valide. Dans ce cas nous allons directement appeler le fournisseur de données avec l'identité pivot renvoyée par FranceConnect. Vous pouvez accédez à l'ensemble des identifiants valides sur le dépot de FranceConnect.
Afin que l'environnement d'intégration fonctionne il est impératif de demander les scopes relatifs à l'identité pivot lors de votre authentification auprès de FranceConnect. Les scopes obligatoires sont :
- given_name
- family_name
- birthdate
- gender
- birthplace
- birthcountry
- preferred_username
Il est possible d'utiliser les alias de scope tel que précisé dans la documentation de FranceConnect.
À noter que seules certaines identités sont prises en compte dans les cas de test, le plus souvent la première de la liste (Angela DUBOIS). S'il n'y a pas de cas de test, vous recevrez la réponse générique tel que défini dans les fichiers swagger de l'api.
Si vous souhaitez ajouter des cas de test, merci de vous réferrez à la section Ajouter des données de test.
Les données de tests de FranceConnect se trouvent dans le dossier payloads/france_connect/
Il est possible dans ce dépôt de faire un mapping jeton <-> données FranceConnect, et derrière faire un mapping Données FranceConnect <-> réponse de l'API.
Par exemple pour api/v2/etudiants-boursiers:
- Un mapping valide pour FranceConnect: payloads/france_connect/cnous.yaml ;
- Un mapping pour
api/v2/etudiants-boursiersqui prend exactement les paramètres d'identité renvoyés par le fichier ci-dessus: payloads/api_particulier_v2_cnous_student_scholarship/fake_franceconnect_cnous.yml.
Ainsi, l'appel suivant renverra in-fine la réponse définie en 2. :
curl -X GET \
-H "Authorization: Bearer cnous" \
https://staging.particulier.api.gouv.fr/api/v2/etudiants-boursiers?recipient=13002526500013Le jeton cnous correspond à la valeur du paramètre token dans le fichier de
définition de FranceConnect.
À noter que les scopes renvoyés par FranceConnect permettent de construire la
réponse adéquate : si les scopes nécessaires pour renvoyer la réponse ne sont pas
présents l'API renverra une 401.
Attention, il y a une divergence entre la production et le staging sur les
champs renvoyés : l'API en production effectue un filtrage des champs en fonction
des scopes. Par exemple ici si cnous_email est absent des scopes, l'API en
production retira le champ email de la réponse. Ce comportement n'existe pas
en staging, l'API renverra la payload définie dans le fichier de ce dépôt sans
aucun filtrage.
Pour contourner ce problème, il faut retirer les champs de la payload finale.
Vous pouvez vous référer à l'exemple
payloads/api_particulier_v2_cnous_student_scholarship/fake_france_connect_cnous_with_less_scopes.yml,
où les clés nom, prenom, prenom2, dateNaissance, lieuNaissance, sexe
ont été omises.
Plusieurs exemples existent pour tous les endpoints FranceConnectés dans le dossier france_connect, avec une description indiquant la réponse associée sur le fournisseur de données.
Lorsque des nouvelles données sont poussées sur la branche develop, le système
effectue des vérifications sur la cohérence à l'aide d'une suite de tests
automatisés. Si tout est OK, le système notifie l'API afin que celle-ci prenne
en compte les nouvelles données.
En cas de problème, il est possible d'effectuer une recharge des données en lançant la commande suivante :
bundle exec ruby bin/reload_mock_backend.rbSi vous êtes développeur, référez-vous à la section Développement ci-dessous.
Si vous êtes un fournisseur de données :
- Pour un endpoint ayant déjà un dossier dans
payloads/:- Si vous êtes à l'aise avec Github, vous pouvez ajouter vous-même les fichiers des cas de tests que vous souhaitez, au travers d'une Pull Request ;
- Autrement, vous pouvez ouvrir un ticket pour que l'on vous accompagne sur l'implémentation : Ajout de nouvelles données
- Pour un endpoint n'ayant pas encore de dossier dans
payloads/:- Si vous êtes à l'aise avec Github, vous pouvez créer un dossier dans
future_payloads/à l'aide d'une Pull Request ; - Autrement, vous pouvez ouvrir un ticket pour que l'on vous accompagne sur l'implémentation : Ajout d'un endpoint manquant.
- Si vous êtes à l'aise avec Github, vous pouvez créer un dossier dans
- ruby 3.2.0
bundle installbundle exec rspecRéférez-vous à tokens/
- Identifier l'operation_id (dans les fichiers swaggers:
x-operationId) ; - Executer la commande :
bundle exec ruby bin/bootstrap_payload.rb operation_id; - La commande crée un dossier avec un
default.yamlque vous devez adapter pour que la suite de tests passe (cf plus bas).
Par défaut, la commande se base sur les fichiers OpenAPI en staging.
Pour utiliser les fichiers openapi locaux (dossier openapi_files), utilisez la variable d'environnement LOCAL=true
-
Pour API Particulier, si un jeton ne possède pas l'ensemble des scopes pour un fournisseur de données, l'environnement de test ignore le filtrage sur ces scopes (contrairement à la production qui filtre en fonction des scopes).
Par exemple, si votre jeton possède l'ensemble des autorisations pour
/v2/etudiants-boursierssauf celle de récupérer l'e-mail (cnous_email), la production retirera le champemailde la réponse, mais pas l'environnement de test.Pour palier ce problème, le plus simple reste de créer une réponse spécifique avec moins de champ.
-
Pour les endpoints qui ne sont pas encore présents dans ce dépôt, des ajustements techniques vis-à-vis des paramètres à prendre en compte peuvent être nécessaires.
Si ces limitations sont problématiques pour votre développement et intégration, nous vous invitons à ouvrir un ticket.