Tutoriel : publier une API de gestion d'utilisateurs

Statut documentaire : tutorial — voir Maturité et preuves.

Objectif

Construire un petit module UserManagement, vérifier le modèle, puis publier des routes HTTP au-dessus des capacités du Runtime.

La séquence est volontairement stricte : modèle d'abord, service ensuite. Une route ne doit pas servir à masquer un modèle qui ne se charge pas correctement.

Structure cible

UserManagement/
├── packages/
│   └── UserManagement.package.yaml
├── meta/
│   └── models/
│       └── UserManagement/
│           ├── ClassItems.manifest.yaml
│           └── User.model.yaml
└── services/
    └── UserManagement.service.yaml

1. Déclarer le package

package:
  name: UserManagement
  enabled: true

2. Déclarer le manifeste

Utilisez un préfixe applicatif possédé par le projet. usr# est utilisé ici à titre d'exemple.

classes:
  - class:
      classId: usr#user
      name: User
      type: entity

Ne réutilisez pas un préfixe plateforme pour un concept propre à l'application.

3. Déclarer le modèle User

class:
  classId: usr#user
  name: User
  type: entity
  concepts:
    - concept:
        name: Entity
        facets:
          - facet:
              type: hypergraph
              name: main
              fields:
                - Name: String
                - Age: Integer
                - Email: String
                - Company:
                    type: String
                    nullable: true

Ajoutez ensuite une facette persistante uniquement si le scénario exige un stockage durable.

4. Vérifier le modèle avant de publier

Démarrez l'application avec le package activé et vérifiez :

1. que ClassItems.manifest.yaml est chargé ;
2. que usr#user est unique ;
3. que User est résolu par le Runtime ;
4. que les champs ont les types attendus ;
5. que les éventuelles contraintes sont valides.

Si cette étape échoue, n'ajoutez pas encore le service HTTP.

5. Ajouter un groupe de services

Le package doit rendre le service chargeable selon le mécanisme de publication supporté par la release.

Exemple conceptuel :

services:
  - name: UserManagementApi
    source: ../../services/UserManagement.service.yaml
    enabled: true

La forme exacte du descripteur est versionnée ; utilisez la référence de votre release pour un fichier destiné à la production.

6. Définir le service HTTP

Le service publie des capacités du modèle, pas une seconde copie du domaine.

service:
  name: UserManagementApi
  basePath: /api/users
  routes:
    - method: GET
      path: /
      action: ListUsers
    - method: GET
      path: /{id}
      action: GetUser
    - method: POST
      path: /
      action: CreateUser
    - method: PUT
      path: /{id}
      action: UpdateUser
    - method: DELETE
      path: /{id}
      action: DeleteUser

Cet extrait décrit le pattern de publication. Les noms d'actions effectifs doivent correspondre à des actions réellement publiées par le modèle et à la grammaire de service de la version utilisée.

7. Publier les opérations CRUD

Les opérations HTTP peuvent être mappées ainsi :

HTTP	Capacité métier	Remarque
GET /api/users	collection User	lecture filtrable/paginable selon le service
GET /api/users/{id}	résolution d'un User	404 si absent
POST /api/users	création	validation métier avant commit
PUT /api/users/{id}	modification	préserver identité et contraintes
DELETE /api/users/{id}	suppression	appliquer autorisations et règles métier

8. Sécurité

La publication HTTP crée une frontière de sécurité distincte. Au minimum :

• authentifier le caller lorsque nécessaire ;
• autoriser au niveau de la capacité métier ;
• ne jamais placer de secret dans une référence d'objet ;
• propager un contexte d'audit ;
• traiter local et distant comme des frontières de confiance explicites.

9. Diagnostics

En cas d'échec, diagnostiquer dans cet ordre :

1. application et package ;
2. manifeste ;
3. modèle User ;
4. actions/collections publiées ;
5. service ;
6. route ;
7. transport ;
8. authentification/autorisation.

Conservez un identifiant de corrélation pour les appels distants afin de relier le diagnostic client et Runtime.

10. Ce que ce tutoriel démontre

• un modèle métier est déclaré indépendamment de sa projection HTTP ;
• la publication arrive après la validation du modèle ;
• les services exposent des capacités publiées ;
• le même Runtime peut être utilisé localement ou derrière une frontière distante ;
• les détails de transport ne doivent pas contaminer le modèle de domaine.