La question à se poser en premier
Avant d'écrire du code, regardez ce qui existe. La plupart des besoins courants sont déjà couverts : accès à un système de fichiers, à un dépôt de code, à une base de données, à un outil de suivi de tickets.
Reprendre un serveur existant vous donne un composant testé, maintenu, et dont les cas limites ont déjà été rencontrés par d'autres. Écrire le vôtre se justifie quand l'outil que vous voulez exposer est interne, ou quand vos règles d'accès ne ressemblent à celles de personne.
Ce qu'un serveur expose
Trois natures de choses, et les confondre est l'erreur de conception la plus fréquente.
Les outils : des actions. Le modèle peut décider de les appeler. « Créer un ticket », « exécuter une requête », « envoyer un message ».
Les ressources : des données que le client peut lire. Un fichier, un enregistrement, le contenu d'une page. Leur lecture ne produit pas d'effet.
Les invites : des gabarits de demande préparés, proposés à l'utilisateur.
La distinction qui compte pour la sécurité : un outil agit, une ressource se lit. Exposer en outil ce qui aurait dû être une ressource donne au modèle la capacité de déclencher des effets là où une lecture aurait suffi.
Décrire les outils pour qu'ils soient bien utilisés
C'est le point qui décide de la qualité d'un serveur, et il est plus rédactionnel que technique.
Le modèle choisit un outil d'après son nom et sa description. Une description vague produit des appels au mauvais moment, avec de mauvais arguments.
Trois règles :
Nommez par l'intention, pas par l'implémentation. rechercher_client vaut mieux que query_db_v2.
Dites quand ne pas l'utiliser. « Ne pas utiliser pour les clients archivés, voir rechercher_archive » évite plus d'erreurs qu'une longue description du fonctionnement normal.
Décrivez chaque paramètre, avec son format attendu et un exemple. Une date sans format annoncé sera envoyée dans trois formats différents.
Commencer petit
Un serveur avec trois outils bien décrits est plus utile qu'un serveur avec trente outils approximatifs. Au-delà d'une certaine quantité, le modèle choisit moins bien, et les erreurs de sélection augmentent.
Commencez par les lectures, ajoutez les écritures ensuite, une fois l'usage observé. C'est aussi la progression la plus sûre : une lecture mal choisie coûte une réponse inutile, une écriture mal choisie coûte une donnée modifiée.
Tester avant de brancher
Un serveur se teste seul, sans client, en lui envoyant des appels directs : lister les outils, en appeler un, vérifier la réponse et la forme des erreurs.
Vérifiez en particulier ce qui se passe sur les cas limites : argument manquant, valeur hors domaine, ressource inexistante. Un serveur qui renvoie une erreur claire permet au modèle de se corriger ; un serveur qui renvoie une réponse vide le fait boucler.
À retenir
Cherchez un serveur existant avant d'écrire. Un outil agit, une ressource se lit : ne confondez pas. La qualité tient dans les descriptions, y compris le « quand ne pas l'utiliser ». Peu d'outils, lectures d'abord, et des erreurs explicites.