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 :

• apientreprise/v3and_more/insee/etablissements (entreprise v3+)
• apiparticulier/v3andmore/cnav/quotientfamilial (particulier v3+)
• apiparticulier/v2/cnav/quotientfamilial (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.resourcename) correspond a SwaggerData.get('provider.resourcename.property') dans les specs rswag.

Swagger dans swaggershared/

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

Definitions partagees : swaggershared/00commons.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/apientreprise/ ou apiparticulier/
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/apiparticulier/fichespratiquesentries.fr.yml (fiche modaliteappelfranceconnect, 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 callid: — callid est un

champ legacy qui peut contenir des valeurs obsoletes (ex. educationnationale/statutelevescolarise liste encore FranceConnect dans callid alors que ce n'est plus une modalite disponible ; seul parameters: pilote le badge FranceConnect affiche ailleurs sur le site, cf. site/app/views/apiparticulier/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 :

``bash cd site && bundle exec rspec spec/features/apiparticulier/casusages_spec.rb ``