Publication de services et OpenAPI

Statut documentaire : reference — voir Maturité et preuves.

Une API logiCells doit être la projection d'une capacité du modèle, pas une seconde définition manuelle du métier.

Chaîne de publication

Concept
  -> published action
  -> service adapter
  -> route / protocol mapping
  -> OpenAPI or other machine-readable contract

Une action publiée définit le verbe métier et sa signature typée. Un adaptateur de service choisit ensuite comment cette capacité est exposée.

Exemple de capacité publiée

actions:
  - action:
      name: Verify
      type: ObjectItem
      published: true
      params:
        - Login:
            dataType: String
            paramType: ptIn
        - Password:
            dataType: String
            paramType: ptIn
        - Result:
            dataType: Boolean
            paramType: ptReturn

OpenAPI

Lorsque le service HTTP supporte la génération d'un contrat machine-readable, OpenAPI doit être dérivé de la surface effectivement publiée :

• routes réellement exposées ;
• paramètres d'entrée ;
• types de retour ;
• erreurs documentées ;
• exigences de sécurité.

Ne maintenez pas manuellement un contrat OpenAPI qui diverge du modèle publié.

Sécurité

published: true ne signifie pas « accessible à tous ». La publication, l'authentification, l'autorisation, la validation et la visibilité sont des couches distinctes.

Règles

• nommer les actions avec des verbes métier ;
• ne pas encoder GET, POST, RPC ou un nom de framework dans l'action ;
• traiter les opérations longues comme des processus ou jobs ;
• versionner les changements de signature comme des changements de contrat ;
• garder les classes et modules d'implémentation privés hors de la documentation publique.