Skip to content

Latest commit

 

History

History
299 lines (215 loc) · 13.4 KB

README.md

File metadata and controls

299 lines (215 loc) · 13.4 KB
Raw

Données de tests API Entreprise v3+ & API Particulier / Utilisation de l'environnement de test

Tests

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

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

Fonctionnement

Un dossier de cas de tests pour chaque endpoint :

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

Format des cas de test :

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 ;

Exemples d'appel d'un cas de test :

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.

Appels avec FranceConnect - Uniquement pour API Particulier

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.

En utilisant le FranceConnect d'integration

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.

En utilisant les faux jetons FranceConnect

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.

Déploiement des 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.rb

Contribution : Ajouter des données de test

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.

Développement

Installation en local

Dépendances

  • ruby 3.2.0
bundle install

Lancer la suite de tests pour vérifier les payloads

bundle exec rspec

Générer un jeton

Référez-vous à tokens/

Ajout d'un nouvel endpoint

  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. Pour utiliser les fichiers openapi locaux (dossier openapi_files), utilisez la variable d'environnement LOCAL=true

Limitations

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