POST seulement ? Mettons fin à ce débat absurde sur la conception des API

Récemment, une discussion sur la conception d'API en utilisant "POST seulement" a attiré mon attention. Après m'être penché sur ce débat, j'ai découvert que non seulement la question soulevée est dénuée de sens, mais qu'elle révèle également une mauvaise compréhension de nombreux développeurs de l'essence de la conception des API. Aujourd'hui, plongeons au cœur des idées fondamentales de la conception d'API et voyons pourquoi ce débat ne devrait pas exister en premier lieu.

La méprise du "POST seulement"#

Les développeurs qui plaident pour l'utilisation de "POST seulement" pour remplacer les spécifications API RESTful n'ont clairement pas saisi le point le plus important de la conception des API. Leurs arguments incluent généralement :

1. Simplification de la conception : Une méthode peut tout gérer
2. Sécurité : Les paramètres POST n'apparaissent pas dans l'URL
3. Flexibilité : POST peut envoyer n'importe quelle structure de données

À première vue, ces arguments semblent avoir du sens. Mais en réalité, cette vision confond le choix des méthodes HTTP avec les styles de conception d'API, deux niveaux de problèmes différents. POST n'est qu'une méthode du protocole HTTP, tandis que REST est un style de conception d'API.

L'essence de la conception d'API#

Avant de discuter de styles spécifiques d'API, nous devons comprendre quel est le but central de la conception d'API. Une bonne API doit être :

1. Claire et compréhensible : Les autres développeurs (y compris vous-même à l'avenir) doivent être capables de comprendre intuitivement l'objectif de chaque endpoint
2. Cohérente : Suivre certaines spécifications pour réduire les coûts d'apprentissage
3. Extensible : Capable de contrôler facilement les versions et d'étendre ses fonctionnalités
4. Efficace : Prendre en compte l'efficacité en termes de performances et d'utilisation des ressources

API RESTful : Plus qu'un simple choix de méthodes HTTP#

L'API RESTful n'est qu'un des nombreux styles de conception d'API, se concentrant sur les ressources et les opérations sur les ressources. Prenons un simple système de blog comme exemple pour voir comment une API RESTful est conçue :

1. Obtenir tous les articles :

2. Obtenir un article spécifique :

3. Créer un nouvel article :

4. Mettre à jour un article :

5. Supprimer un article :

Dans cet exemple, on peut voir :

• L'API est conçue autour de la ressource "article"
• Différentes méthodes HTTP sont utilisées pour représenter différentes opérations
• La structure de l'URL est claire, indiquant la ressource concernée

Cette approche de conception rend l'API plus intuitive et auto-explicative, la rendant facile à comprendre pour les développeurs.

RPC : Comprendre le style d'API derrière "POST seulement"#

L'objectif de la conception d'une API de style RPC (Remote Procedure Call) est de faire en sorte que les appels de services distants soient aussi simples que des appels de fonctions locales.

Fait intéressant, ceux qui plaident pour "POST seulement" ne réalisent peut-être pas qu'en fait ils décrivent le style RPC.

Comparé aux API RESTful, le RPC se concentre davantage sur l'opération elle-même que sur la ressource. C'est pourquoi les API de style RPC utilisent généralement une forme "verbe + nom", comme getProduct(productId) ou createUser(userData).

Dans de nombreuses implémentations RPC, toutes les opérations sont généralement envoyées via des requêtes POST au même endpoint, avec l'opération spécifique et les paramètres spécifiés dans le corps de la requête. C'est pourquoi l'idée de "POST seulement" est en réalité plus proche de RPC que de REST.

Par exemple, une requête "récupérer un produit" de style RPC basée sur HTTP pourrait ressembler à ceci :

Les frameworks RPC modernes, comme gRPC, offrent des implémentations plus puissantes et plus efficaces. Prenons celui-ci comme exemple pour illustrer le style RPC :

Premièrement, nous définissons le service et le format du message (en utilisant Protocol Buffers) :

Ensuite, utiliser ce service dans un client Node.js est aussi simple que d'appeler une fonction locale :

Dans cet exemple de style RPC, on peut voir :

1. La définition du service liste clairement toutes les opérations disponibles (dans cet exemple simplifié, GetArticle et CreateArticle).
2. Chaque opération a des types de requête et de réponse clairement définis.
3. Le code client ressemble à un appel de fonction asynchrone locale, en utilisant await pour attendre le résultat, ce qui cache encore plus la complexité de la communication réseau.
4. Il n'est pas nécessaire de construire manuellement des requêtes HTTP ou de parser des réponses JSON.

Bien que la couche sous-jacente puisse encore utiliser HTTP/2 comme protocole de transport, les frameworks RPC (comme gRPC) offrent aux développeurs une couche d'abstraction qui rend les appels distants aussi simples que les appels de fonctions locales.

Ainsi, nous pouvons voir que la plupart des débats sur "POST seulement" et les API RESTful devraient essentiellement être des discussions sur ces deux styles d'API : REST et RPC. Cependant, l'essentiel est de reconnaître que ces deux styles ont chacun leurs scénarios d'application, et le choix devrait se baser sur les besoins spécifiques du projet, et non sur des préférences personnelles.

REST vs RPC : Pas de supériorité ou d'infériorité absolue#

Maintenant que nous comprenons les différences entre REST et RPC, examinons leurs scénarios d'application respectifs :

1. REST est adapté pour :
   • Applications orientées ressources (tels que les systèmes de gestion de contenu, les plateformes de blog, les sites d'e-commerce)
   • Scénarios nécessitant un bon support du cache (les requêtes GET sont naturellement mises en cache)
   • Projets souhaitant tirer parti des sémantiques HTTP (comme l'utilisation de codes d'état appropriés)
   • API publiques nécessitant une bonne découvrabilité et auto-description
2. RPC est adapté pour :
   • Applications orientées actions (comme les opérations de traitement de données complexes, le contrôle des flux de travail)
   • Systèmes nécessitant des performances élevées et une faible latence (comme les systèmes de trading en temps réel)
   • Communication entre microservices internes (qui peuvent nécessiter un passage de paramètres plus flexible)
   • Lorsque les opérations ne peuvent pas simplement être mappées aux opérations CRUD (Create, Read, Update, Delete)

Le choix du style doit être basé sur vos besoins spécifiques. Dans certains cas, vous pourriez même utiliser un mélange de ces deux styles au sein du même système pour répondre aux besoins de différentes parties.

Conclusion#

1. Le cœur de la conception d'API réside dans la clarté, la cohérence, l'extensibilité et l'efficacité, et non dans l'adhésion à une méthode ou un style particulier.
2. RESTful et RPC sont deux paradigmes de conception d'API matures. Le choix entre eux devrait se baser sur les besoins du projet, et non sur des préférences personnelles.
3. Si vous décidez d'utiliser "POST seulement", alors veuillez concevoir votre API selon le style RPC. Comme RESTful, c'est une spécification d'API couramment utilisée dans l'industrie, mais elle doit être utilisée dans des scénarios appropriés.
4. Ne vous laissez pas distraire par des détails techniques superficiels. Ce qui importe vraiment, c'est de savoir si votre API peut effectivement répondre aux besoins de vos utilisateurs et de votre entreprise.
5. Lors de la conception des API, passez plus de temps à réfléchir à votre modèle de ressources, à votre logique métier, et aux besoins de vos utilisateurs, plutôt qu'à vous obséder sur la méthode HTTP à utiliser.

Portons notre attention sur la conception d'API vraiment excellentes et laissons de côté ces arguments futiles. Après tout, la technologie est faite pour résoudre des problèmes, non pour en créer.