# Edit Endpoint

> Modifier la documentation d'un endpoint API : fiche metier (perimetre, FAQ, keywords, description) ou swagger (schema OpenAPI, attributs, tags). Utiliser quand l'utilisateur veut editer, ajouter ou mettre a jour un endpoint dans le catalogue API Entreprise ou API Particulier. Triggers : "modifier la fiche", "ajouter un endpoint", "mettre a jour le swagger", "changer la description", "ajouter une FAQ", "modifier le perimetre", "editer endpoint".

- Skill: `datagouv/edit-endpoint` (Agent Skill)
- Install (CLI): `npx skillmds@latest add datagouv/edit-endpoint`
- Raw SKILL.md: https://api.skillmd.com/api/skills/datagouv/edit-endpoint/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: datagouv (https://skillmd.com/u/datagouv)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/datagouv/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 :

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

## Format d'un fichier endpoint

```yaml
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 :

```bash
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 :

```bash
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

```bash
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 :
  ```bash
  cd site && bundle exec rspec spec/features/api_particulier/cas_usages_spec.rb
  ```