edit-endpoint

Edit an endpoint

Locate the file

Everything is in commons/endpoints/ :

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

Find an endpoint by uid:

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

Format of an endpoint file

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"

Field `controller`

The controller must point to the real Rails controller on the siade side (without #action). Used by the provider dashboard to link the sheet to the access_logs.controller. To find it:

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

Examples:

api_entreprise/v3_and_more/insee/etablissements (company v3+)
api_particulier/v3_and_more/cnav/quotient_familial (individual v3+)
api_particulier/v2/cnav/quotient_familial (individual v2 legacy)

Business sheet

Edit the fields under fiche: (excluding swagger:). Validate:

cd site && bundle exec rspec spec/stores/

Swagger

Embedded swagger

Edit fiche[].swagger: in the endpoint file. The doted key (provider.resource_name) corresponds to SwaggerData.get('provider.resource_name.property') in the rswag specs.

Swagger in `_swagger_shared/`

Multi-endpoint providers keep their swagger in _swagger_shared/<provider>.yml : insee, cnav, dgfip, inpi_rne, mi, infogreffe, cnous, mesri, men, france_travail, gip_mds.

Shared definitions: _swagger_shared/00_commons.yml (SIREN/SIRET params), _swagger_shared/civility.yml (pivot identity).

Validate the swagger

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

Add an endpoint

Copy the template: commons/endpoints/template.entreprise.yml.example (or particulier)
Create the file in commons/endpoints/api_entreprise/ or api_particulier/
Fill in sheet + swagger
Create the rswag spec in siade/spec/requests/
cd siade && bin/generate_swagger.sh