Edit Endpoint

Editer un endpoint

Localiser le fichier

Tout est dans commons/endpoints/ :

commons/endpoints/
  api_entreprise/*.yml      # endpoints API Entreprise
  api_particulier/*.yml     # endpoints API Particulier
  _swagger_shared/          # swagger partage (ancres YAML entre endpoints)

Trouver un endpoint par uid :

grep -r "uid: 'provider/resource'" commons/endpoints/

Format d'un fichier endpoint

fiche:
  - uid: 'provider/resource'
    path: '/v3/provider/resource/{param}'
    controller: 'api_entreprise/v3_and_more/provider/resource'  # cf. section dediee
    position: 501                    # ordre dans le catalogue
    opening: protected               # protected ou public
    provider_uids: ['provider']
    call_id: "SIRET"
    keywords: [mot, cle]
    perimeter:
      entity_type_description: |+    # qui est concerne
      geographical_scope_description: |+
      updating_rules_description: |+
      know_more_description: |+
      entities: [entreprises, associations]
    data:
      description: |+                # description des donnees renvoyees
    parameters:
      - Description du parametre
    format:
      - Donnee structuree JSON
    faq:
      - q: "Question ?"
        a: |+ Reponse
    historique: |+                    # changelog entre versions
    swagger:
      provider.resource_name:        # cle dottee = SwaggerData.get path
        title: "Titre swagger"
        description: "Description technique"
        tags: ["Categorie"]
        attributes:                  # ou document_url_properties pour PDF
          champ:
            type: "string"
            title: "Titre"
            example: "valeur"

Champ controller

Le controller doit pointer vers le controller Rails reel cote siade (sans #action). Sert au dashboard fournisseur pour relier la fiche aux access_logs.controller. Pour le retrouver :

cd siade && bundle exec rails routes | grep '<provider>'

Exemples :

• api_entreprise/v3_and_more/insee/etablissements (entreprise v3+)
• api_particulier/v3_and_more/cnav/quotient_familial (particulier v3+)
• api_particulier/v2/cnav/quotient_familial (particulier v2 legacy)

Fiche metier

Modifier les champs sous fiche: (hors swagger:). Valider :

cd site && bundle exec rspec spec/stores/

Swagger

Swagger embarque

Modifier fiche[].swagger: dans le fichier endpoint. La cle dottee (provider.resource_name) correspond a SwaggerData.get('provider.resource_name.property') dans les specs rswag.

Swagger dans _swagger_shared/

Les providers multi-endpoints gardent leur swagger dans _swagger_shared/<provider>.yml : insee, cnav, dgfip, inpi_rne, mi, infogreffe, cnous, mesri, men, france_travail, gip_mds.

Definitions partagees : _swagger_shared/00_commons.yml (params SIREN/SIRET), _swagger_shared/civility.yml (identite pivot).

Valider le swagger

cd siade && bundle exec rspec spec/requests/api_entreprise/v3_and_more/<provider>/<resource>/
bin/generate_swagger.sh

Ajouter un endpoint

1. Copier le template : commons/endpoints/template.entreprise.yml.example (ou particulier)
2. Creer le fichier dans commons/endpoints/api_entreprise/ ou api_particulier/
3. Remplir fiche + swagger
4. Creer la spec rswag dans siade/spec/requests/
5. cd siade && bin/generate_swagger.sh
6. Si parameters: contient FranceConnect (endpoint API Particulier), mettre a jour la liste des API FranceConnectees (section dediee ci-dessous)

Modalite d'appel FranceConnect (API Particulier)

Des qu'un endpoint API Particulier gagne ou perd FranceConnect dans son champ parameters: (nouvel endpoint ou modification d'un endpoint existant), mettre a jour le tableau "Liste des API FranceConnectees" dans site/config/locales/api_particulier/fiches_pratiques_entries.fr.yml (fiche modalite_appel_france_connect, ancre liste-api-particulier-franceconnectees).

Ce tableau est statique (markdown ecrit a la main) : rien ne le regenere depuis les fiches, donc rien ne le garde synchronise automatiquement — une modification de parameters: sans mise a jour de ce tableau le rend perime silencieusement.

• Champ de reference : parameters:, pas call_id: — call_id est un champ legacy qui peut contenir des valeurs obsoletes (ex. education_nationale/statut_eleve_scolarise liste encore FranceConnect dans call_id alors que ce n'est plus une modalite disponible ; seul parameters: pilote le badge FranceConnect affiche ailleurs sur le site, cf. site/app/views/api_particulier/endpoints/_endpoint.html.erb et _details.html.erb).
• Nom du fournisseur affiche dans la colonne : reprendre exactement le name: du provider dans site/config/locales/api_particulier/providers.fr.yml (acronymes en majuscules : CNAF & MSA, MESRI, CNOUS, pas Cnaf & msa/Mesri/Cnous).
• Lien [Fiche metier] : <%= endpoint_path(uid: '...') %> avec le uid exact de l'endpoint — un uid errone casse le rendu de la page.
• Valider apres modification :

  cd site && bundle exec rspec spec/features/api_particulier/cas_usages_spec.rb