Aller au contenu
EN FR

Services et publication

Statut documentaire : guide — voir Maturité et preuves.

La publication doit exposer des capacités conceptuelles, pas dupliquer le modèle métier dans une seconde couche d'API.

Trois niveaux

  • Action interne : appelable dans le modèle, une vue, un script ou un processus.
  • Action publiée : volontairement incluse dans un contrat de modèle appelable.
  • Action exposée : action publiée liée à HTTP, MCP, messaging, tooling d'agent ou un autre adaptateur.

Cette séparation permet à l'action conceptuelle de rester stable lorsque le transport externe change.

Mapping d'une action publiée

Un adaptateur de publication résout typiquement :

classe/objet cible
+ action publiée
+ paramètres d'entrée typés
+ contrat de retour/résultat
-> validation adaptateur
-> invocation Runtime
-> mapping de réponse

Les valeurs primitives de requête se mappent directement. Les valeurs conceptuelles doivent utiliser des identifiants stables, références d'objets ou projections déclarées. L'adaptateur doit rejeter une entrée mal formée ou incomplète avant dispatch lorsque l'invalidité est connue à la frontière.

Exemple de service HTTP déclaratif

L'exemple de service du guide est conservé avec la normalisation TXXX -> XXX :

serviceGroupDefinitions:
  - UserManagement:
      uuid: EA588812932A434B87A5F47A795C27E4
      type: HTTP
      moduleClass: DataModuleHTTPServer
      debug: true
      virtualPages:
        - method: GET
          path: /users
          class: PathRequestWebPage
          rewrite: /ClassItem[@name='UserManagement.User']/Collection[@name='Entity']

DataModuleHTTPServer et PathRequestWebPage sont les graphies publiques modernisées des noms de binding d'implémentation utilisés dans l'exemple source. L'exemple est conservé au lieu d'être supprimé à cause du préfixe historique.

Opérations longues

Ne modélisez pas une opération longue comme un unique appel HTTP bloquant. Publiez une action comme Start, Submit, Request ou Finalize, créez/mettez à jour un objet processus, retournez un accusé/référence, puis exposez l'état et les événements.

Publication lisible par machine

OpenAPI et MCP doivent être des projections des mêmes types et actions déclarés, pas des systèmes de types indépendants. Gardez alignés champs obligatoires, identifiants conceptuels, rôles de relations et sémantique de validation.

Voir API de publication, ABI et RPC.