API Public v1

L'API Public se trouve sous packages/cli/src/public-api/v1/. Les handlers sont des modules de route express-openapi-validator; les spécifications OpenAPI sont en YAML dans le répertoire spec/ de chaque handler.

Ajouter un endpoint

1. Handler — handlers/<feature>/<feature>.handler.ts
   • Exporter des tableaux middleware indexés par x-eov-operation-id.
   • Pour les endpoints protégés par scope, utiliser publicApiScope() ou apiKeyHasScopeWithGlobalScopeFallback() (ils tagent le middleware d'application du scope avec __apiKeyScope) et ajouter un x-required-scope correspondant dans le YAML de chemin; utiliser none pour les endpoints sans scope de clé API (voir scope-parity.test.ts).
   • Déléguer à la même couche de service/contrôleur que l'API REST interne. Parser l'entrée avec les DTOs @n8n/api-types, appeler Container.get(SomeService) ou Container.get(SomeController), mapper les erreurs — ne pas accéder directement aux repositories ou dupliquer la logique métier dans le handler. Les handlers plus anciens comme handlers/credentials/ et handlers/workflows/ précèdent ce pattern; les suivre uniquement pour le câblage des middleware/OpenAPI, pas pour l'accès aux données.
2. Spécification OpenAPI de chemin — handlers/<feature>/spec/paths/<path>.yml
   • Définir tags: [<TagName>] correspondant à un tag de haut niveau dans openapi.yml.
3. Enregistrer le chemin — ajouter une entrée $ref sous paths: dans openapi.yml.
4. Types de requête — ajouter un namespace dans packages/cli/src/public-api/types.ts quand le handler a besoin de paramètres de requête/corps typés.
5. Manifeste de couverture — ajouter chaque nouvel endpoint OpenAPI à packages/nodes-base/nodes/N8n/n8n-api-coverage.json.

Tableau tags dans openapi.yml

Quand on ajoute ou édite le tableau tags: de haut niveau dans packages/cli/src/public-api/v1/openapi.yml, conserver les entrées triées alphabétiquement par name. Insérer le nouveau tag dans l'ordre; ne pas l'ajouter à la fin.

tags:
  - name: Audit
    description: Operations about security audit
  - name: CommunityPackage
    description: Operations about community packages
  # … tags restants en ordre A→Z par name

scope-parity.test.ts affirme cet ordre — la CI échoue si les tags sortent de l'ordre alphabétique.

Handlers de référence

• GET simple via service: handlers/insights/
• CRUD via service/contrôleur: handlers/variables/, handlers/folders/, handlers/projects/, handlers/data-tables/
• Multipart: handlers/n8n-packages/ (voir aussi packages/cli/src/modules/n8n-packages/CLAUDE.md)