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

• Quick start
• Fonctionnement
  • Un dossier de cas de tests pour chaque endpoint
  • Format des cas de test
  • Exemples d'appel d'un cas de test
  • Appels avec FranceConnect - Uniquement API Particulier
• Contribution : Ajouter des données de test
• Développement
  • Installation en local
  • Lancer la suite de tests pour vérifier les payloads
  • Génerer un jeton
  • Ajout d'un nouvel endpoint
  • Déploiement des données
• Limitations

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/datagouv/apistration/develop/mocks/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 'nomNaissance=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/impots

Pour 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/impots

Les 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: 422 et 403 ;
• Pour API Particulier: 400 et 401.

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 : API Particulier agit alors comme un fournisseur de données agrégé adossé à FranceConnect. On passe un jeton FranceConnect à la place des paramètres d'identité classiques. À partir de ce jeton, l'API interroge FranceConnect (introspection du jeton) pour récupérer l'identité pivot de l'usager (données de civilité, un exemple ici), qui est ensuite formatée pour effectuer l'appel auprès du fournisseur de données correspondant.

En tant que fournisseur de données référencé par FranceConnect, l'identité pivot nous est renvoyée systématiquement : il n'y a pas de scope d'identité pivot à demander côté intégrateur. En revanche, le jeton FranceConnect doit porter les scopes métier de l'endpoint appelé, définis dans commons/data/authorizations.yml. Sans ces scopes métier, l'API renvoie une 401.

Il est possible d'envoyer sur nos serveurs de staging un vrai jeton émis par le service d'intégration de FranceConnect. Dans ce cas, le seul appel réseau réellement effectué vers l'extérieur est l'introspection du jeton auprès de FranceConnect, qui nous renvoie l'identité pivot. Le fournisseur de données en aval (CNAV, CNOUS, ANTS…) reste, lui, mocké en staging : sa réponse est construite à partir d'un mapping local dont la clé est l'identité pivot renvoyée par FranceConnect (cf. la section En utilisant les faux jetons FranceConnect ci-dessous). Vous n'obtenez donc une réponse métier que s'il existe un cas de test correspondant à cette identité. Vous pouvez accéder à l'ensemble des identités valides sur le dépot de FranceConnect.

Le jeton FranceConnect doit porter les scopes métier de l'endpoint appelé, définis dans commons/data/authorizations.yml (cf. l'exemple ANTS plus bas). L'identité pivot, elle, nous est renvoyée d'office par FranceConnect et n'a pas à être demandée via des scopes dédiés.

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

Vous pouvez utiliser la documentation de FranceConnect pour construire votre propre environnement d'intégration pour tester de bout-en-bout, ou pour un rapide test vous pouvez utiliser l'espace d'intégration d'exemple de FranceConnect :

Exemple step-by-step avec l'endpoint ANTS /v3/ants/extrait_immatriculation_vehicule/france_connect :

1. Récupérer un access_token sur FC v2 sandbox

   a. Ouvrir la page du fournisseur de service de démonstration

   https://fsp1-low.sbx.fcp.fournisseur-de-service.fr/login
   

   b. Ajouter les scopes ants demandés pour le token

   openid ants_extrait_immatriculation_vehicule_identite_particulier ants_extrait_immatriculation_vehicule_adresse_particulier ants_extrait_immatriculation_vehicule_statut_rattachement ants_extrait_immatriculation_vehicule_donnees_immatriculation_vehicule ants_extrait_immatriculation_vehicule_caracteristiques_techniques_vehicule
   

   c. Cliquer sur le bouton FranceConnect pour commencer la cinématique

   d. Sélectionner le fournisseur d'identité fip1-low

   e. Utiliser le compte "test" avec mot de passe "123"

   d. Finaliser la cinématique

   e. Copier l'access_token reçu

2. Appeler API SIV géré par API Particulier

   curl "https://staging.particulier.api.gouv.fr/v3/ants/extrait_immatriculation_vehicule/france_connect?recipient=13002526500013&immatriculation=FC-456-CD" -H "Authorization: Bearer $access_token"

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:

1. Un mapping valide pour FranceConnect: payloads/france_connect/cnous.yaml ;
2. Un mapping pour api/v2/etudiants-boursiers qui 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=13002526500013

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

Attention, l'identité pivot renvoyée par FranceConnect ne contient jamais de nom d'usage : seuls family_name, given_name, gender, birthdate, birthplace et birthcountry sont garantis (ce sont les seuls scopes demandés, voir hub_identity_scopes dans siade/app/interactors/france_connect/validate_response.rb). Le paramètre nom_usage est donc systématiquement nil pour un appel FranceConnect réel. N'ajoutez jamais de clé nomUsage dans les params d'un fichier fake_france_connect_*/france_connect_* : aucune requête réelle ne pourra jamais produire cette clé, le mapping échouera silencieusement et l'appel tombera en 404 (ou sur un appel amont réel) au lieu de renvoyer le cas de test attendu. nomUsage n'a de sens que dans les fixtures *_with_civility, où l'appelant le fournit lui-même en paramètre de requête.

siade/config/mock_payloads est un lien symbolique vers mocks/payloads : les deux dépôts partagent exactement les mêmes fichiers, et l'API SIADE lit ces fichiers directement sur disque.

Cette lecture est mise en cache en mémoire, par operation_id, pour toute la durée de vie du process (MockDataBackend, aucun TTL, jamais invalidé automatiquement). Ce n'est pas un problème en pratique : chaque déploiement redémarre les workers de l'API SIADE dans le cadre normal du script de déploiement, donc un nouveau process prend en compte les nouveaux fichiers de payloads automatiquement, sans étape de rechargement séparée.

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

• ruby 4.0.1

bundle install

bundle exec rspec

Référez-vous à tokens/

1. Identifier l'operation_id (dans les fichiers swaggers: x-operationId) ;
2. Executer la commande : bundle exec ruby bin/bootstrap_payload.rb operation_id ;
3. La commande crée un dossier avec un default.yaml que 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. Les fichiers openapi utilisés proviennent de commons/swagger/ (à la racine du dépôt, générés par siade).

• 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-boursiers sauf celle de récupérer l'e-mail (cnous_email), la production retirera le champ email de 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.