Routes & CRUD

Les routes sont les points d’entrée de votre API. Elles sont regroupées par ressource, et vous pouvez les écrire à la main ou les générer depuis un modèle.

Définir une route

Une route porte une méthode, un chemin, des paramètres et des réponses. Le chemin utilise la syntaxe {{param}} de Restorm : dès que vous tapez {{id}} dans le chemin, le paramètre correspondant apparaît ; le retirer le supprime.

Les paramètres

L’onglet Définition d’une route liste ses paramètres — les paramètres de chemin (créés depuis les placeholders {{param}}) et les paramètres de requête / en-tête que vous ajoutez avec Ajouter un paramètre. Chacun porte un nom, un emplacement (dans), son caractère requis, une description et, en option, un exemple.

La cellule Type est une combo : choisissez un primitif (string, integer, number, boolean) ou l’un des enums nommés du design en un seul clic. Pour les cas plus riches, choisissez Advanced… pour ouvrir une petite fenêtre où vous pouvez :

• faire du paramètre un tableau et choisir son type d’élément (array<string>, …) — un paramètre de requête multi-valeurs ;
• lui donner des valeurs d’énumération inline (l’ensemble autorisé, listé en puces) lorsqu’il n’est pas typé par un enum nommé ;
• Extraire vers un enum nommé — promouvoir ces valeurs inline en un enum partagé (voir Modèles & enums).

Un paramètre peut aussi être relié à une propriété de modèle (colonne Lien modèle), dont il hérite le type, ou être marqué déprécié. Chaque paramètre — son type, son enum, sa dépréciation — se retrouve dans la documentation générée et dans chaque projection de protocole.

Générer le CRUD

Depuis les réglages d’un modèle, Générer le CRUD crée en un clic un groupe de routes nommé d’après le pluriel du modèle, avec six routes :

Route	Méthode & chemin	Réponses
Lister	GET / (paginé)	200
Récupérer	GET /{{id}}	200 · 404
Créer	POST /	201
Remplacer	PUT /{{id}}	200 · 404
Mettre à jour	PATCH /{{id}}	200 · 404
Supprimer	DELETE /{{id}}	204 · 404

La liste est paginée (décalage/offset, 20 éléments par défaut, 100 au maximum). Chaque {{id}} est automatiquement relié à l’identifiant du modèle.

La boîte de dialogue Générer le CRUD propose deux options :

• Remplacer les routes existantes — pour éviter les doublons si vous régénérez.
• Protéger les routes d’écriture par authentification — la création, le remplacement, la mise à jour et la suppression exigent alors un jeton (bearer), tandis que les lectures restent publiques.

Elle rappelle aussi que le CRUD est servi dans chaque protocole : routes REST, requêtes et mutations GraphQL, méthodes gRPC, jeu d’entités OData et opérations SOAP (voir Servir le design en mock).

Générer les routes de recherche

Pour chaque propriété marquée searchable, Générer les routes de recherche ajoute un paramètre de requête relié à la route de liste du modèle (et crée cette route si elle n’existe pas encore).

Authentification

L’authentification se règle à trois niveaux : une valeur par défaut du design, une authentification requise par groupe, et un remplacement par route (qui hérite du groupe par défaut). Les modes disponibles sont Aucune, Bearer (JWT), Clé d’API (en-tête) et Basic.

Les tags

Les tags regroupent les routes pour la documentation et l’export OpenAPI. Ils vivent à deux niveaux : une route porte ses propres tags (son onglet Définition), et un groupe porte des tags partagés (ses réglages) appliqués à chacune de ses routes. Les tags effectifs d’une route sont l’union des deux — un tag commun à tout un groupe se pose donc de préférence une seule fois sur le groupe. Lorsque vous transformez une API importée en design, un tag présent sur toutes les routes d’un groupe est automatiquement remonté sur le groupe.

La dépréciation

Une route (comme une propriété ou un paramètre) peut être marquée dépréciée depuis ses Réglages. Une route dépréciée apparaît grisée dans la liste des Routes et dans les clients générés, et porte un avertissement de dépréciation sur son onglet. Le drapeau se propage dans chaque projection de protocole — le deprecated d’OpenAPI, la directive @deprecated de GraphQL, les descripteurs SOAP et gRPC, et les métadonnées OData — pour que les consommateurs de n’importe quel protocole servi le voient.