Qu'est-ce qu'un endpoint d'API ? Définition, exemples, bonnes pratiques

Qu'est-ce qu'un endpoint d'API ?

Un endpoint d'API (ou point de terminaison) est l'adresse qu'un client appelle pour utiliser une opération précise d'une API : un chemin d'URL combiné à une méthode HTTP, par exemple GET /users/42 pour lire un utilisateur ou POST /users pour en créer un. Le même chemin avec une autre méthode est un autre endpoint. L'ensemble des endpoints forme la surface de l'API.

Les API REST exposent de nombreux endpoints, en général un par ressource et par opération. GraphQL n'en expose le plus souvent qu'un seul (souvent /graphql) et le client décrit dans la requête les données voulues. gRPC nomme ses opérations comme des méthodes d'un service plutôt que comme des chemins d'URL.

Comment fonctionne un endpoint d'API

Un endpoint REST se compose de trois éléments :

• URL de base. Protocole, hôte et préfixe facultatif, par exemple https://api.example.com.
• Chemin. La route vers une ressource, par exemple /users/42. Les paramètres de requête comme ?page=2&limit=20 l'affinent.
• Méthode HTTP. Le verbe qui choisit l'opération : GET, POST, PUT, PATCH ou DELETE.

Voici un appel complet à un endpoint de création d'utilisateur et sa réponse :

POST https://api.example.com/users
Content-Type: application/json
Authorization: Bearer <token>

{ "name": "Alice", "email": "alice@example.com" }

HTTP/1.1 201 Created
Location: /users/43

La méthode compte au-delà du nom. Selon MDN, seule GET est sûre (elle ne modifie rien sur le serveur), et GET, PUT et DELETE sont idempotentes : répéter la requête a le même effet que l'envoyer une fois. POST et PATCH ne le sont pas, d'où la prudence nécessaire pour les rejouer : voir idempotence.

Schémas d'endpoints courants

Règles de conception qui tiennent

• Des noms dans le chemin, des verbes dans la méthode. /users, pas /getUsers.
• Un seul style de nommage. Pluriel ou singulier, kebab-case ou snake_case : choisissez-en un et appliquez-le partout.
• Des chemins qui montrent les relations. /users/42/orders se lit comme « les commandes de l'utilisateur 42 ».
• De vrais codes de statut. 201 après une création, 204 pour un succès sans contenu, 400 pour une requête invalide, 401 si l'appelant n'est pas authentifié, 403 s'il n'a pas le droit, 404 si rien n'existe, 429 pour trop de requêtes, 5xx pour les pannes serveur (MDN, d'après la RFC 9110).
• Pagination et filtres dans la query string. /users?role=admin&page=2.
• Des versions explicites. /v1/users permet de publier des changements incompatibles sous /v2.
• Une spécification lisible par machine. Décrivez chaque endpoint en OpenAPI, comme expliqué dans Qu'est-ce que Swagger.

Erreurs fréquentes sur les endpoints

• Des actions dans le chemin. POST /createUser et ?action=delete contredisent la sémantique des méthodes. Préférez POST /users et DELETE /users/42.
• HTTP 200 avec l'erreur dans le corps. Clients, caches et outils de supervision lisent d'abord le code de statut. Renvoyez 4xx ou 5xx en cas d'échec.
• Des secrets dans l'URL. Jetons et données personnelles dans le chemin ou la query string finissent dans les logs, l'historique du navigateur et les en-têtes Referer. Envoyez-les dans les en-têtes ou le corps.
• Un format d'erreur incohérent. Si un endpoint renvoie {"error": ...} et un autre {"message": ...}, chaque client doit gérer des cas particuliers.
• Aucune vérification d'autorisation par endpoint. L'authentification dit qui appelle. Chaque endpoint doit encore vérifier ce que cet appelant a le droit de faire.
• Pas de limite de débit. Un endpoint sans limite est le premier à tomber en cas d'abus ou de tempête de nouvelles tentatives. Répondez 429 avec un en-tête Retry-After. Contexte : causes du rate limiting des API (article en anglais).

Tester et surveiller les endpoints d'API

Chaque endpoint se vérifie à plusieurs niveaux. Les tests d'API contrôlent qu'il renvoie les bonnes données et le bon statut. Les tests de charge montrent son comportement quand de nombreux clients l'appellent en même temps ; LoadFocus exécute des tests JMeter et k6 depuis 25 régions cloud, et l'offre gratuite inclut jusqu'à 10 utilisateurs virtuels. Une fois l'endpoint en production, le monitoring d'API l'appelle à intervalle régulier et vérifie code de statut, corps, en-têtes et temps de réponse, si bien qu'un 200 avec un mauvais contenu échoue aussi ; l'offre gratuite vérifie toutes les 5 minutes. Pour un coup d'œil ponctuel sur une URL publique, le vérificateur de statut d'API envoie une requête depuis six régions sans inscription. Les causes habituelles d'endpoints lents sont décrites dans Common API performance issues and how to detect them (en anglais), et la supervision dans Qu'est-ce que le monitoring d'API.

Questions fréquentes sur les endpoints d'API

Quelle différence entre une API et un endpoint d'API ?

L'API est l'interface entière : tous les endpoints, leurs schémas, l'authentification et les formats d'erreur. Un endpoint est une opération précise à l'intérieur, par exemple l'appel qui crée un paiement dans une API de paiement.

GET /users et POST /users sont-ils le même endpoint ?

Non. Ils partagent le chemin mais utilisent des méthodes différentes : ce sont deux endpoints, l'un liste les utilisateurs, l'autre en crée un.

Un endpoint est-il la même chose qu'une URL ?

Pas tout à fait. L'URL n'est que l'adresse. L'endpoint est l'URL plus la méthode HTTP, car c'est la méthode qui décide de ce que fait le serveur.

Combien d'endpoints une API doit-elle avoir ?

Autant que son périmètre l'exige. Une petite API ciblée en compte quelques-uns, une grande API de plateforme des centaines. Leur nombre ne mesure pas la qualité ; la cohérence et une bonne documentation, si.

Quelle différence entre les endpoints REST et GraphQL ?

REST répartit les opérations sur de nombreux endpoints, un par ressource et par méthode. GraphQL en a le plus souvent un seul, et la requête indique quels champs renvoyer.

Comment modifier un endpoint sans casser les clients ?

Ajoutez une version au chemin (/v1/users, /v2/users), faites tourner les deux pendant la transition, annoncez une date de retrait pour l'ancienne et documentez les changements.