Les API et les services web
Partie 3 sur 3
7Les API Web d’aujourd’hui : REST
7.1Le principe
En 2000, dans sa thèse de doctorat, l’informaticien américain Roy Fielding, l’un des auteurs du protocole HTTP, a décrit le style d’architecture qui fait le succès du Web, qu’il a appelé REST (Representational State Transfer, « transfert d’un état par sa représentation »). Ses principes ont été repris pour concevoir des API beaucoup plus simples que SOAP :
- tout ce que l’API manipule est une ressource, désignée par une adresse Web, son URL (voir les URL) :
/clients/42désigne le client numéro 42,/clients/42/commandesses commandes ; - on agit sur les ressources avec les méthodes ordinaires de HTTP, toujours les mêmes, au lieu d’inventer une fonction par opération (tableau 1) ;
- le serveur renvoie une représentation de la ressource, le plus souvent en JSON ;
- chaque requête est sans état : elle contient tout ce qu’il faut pour être traitée, notamment la preuve de l’identité de l’appelant, ce qui permet de répartir les requêtes sur autant de serveurs que nécessaire.
| Méthode | Usage | Exemple |
|---|---|---|
GET | lire une ressource ou une liste, sans rien modifier | GET /clients/42 |
POST | créer une nouvelle ressource dans une collection | POST /clients |
PUT | remplacer entièrement une ressource | PUT /clients/42 |
PATCH | modifier une partie d’une ressource | PATCH /clients/42 |
DELETE | supprimer une ressource | DELETE /clients/42 |
7.2Une requête, une réponse
Une requête REST est une requête HTTP ordinaire, comme celle qu’envoie un navigateur pour afficher une page (figure 3). La réponse commence par un code à trois chiffres qui indique le résultat (tableau 2), suivi d’en-têtes et des données. On peut essayer une API depuis la ligne de commande avec l’outil curl, qui envoie des requêtes Web :
curl -H "Authorization: Bearer $JETON" \
https://api.example.org/v1/villes/lyon/previsions
{"ville": "Lyon", "date": "2026-10-23",
"temp": 18, "ciel": "nuageux"}
| Code | Signification |
|---|---|
200 | succès ; la réponse contient les données demandées |
201 | ressource créée |
204 | succès, sans contenu à renvoyer (par exemple après une suppression) |
400 | requête mal formée : paramètre manquant ou invalide |
401 | identité non prouvée : jeton absent, invalide ou expiré |
403 | identité connue, mais droits insuffisants |
404 | ressource introuvable |
429 | trop de requêtes : quota dépassé, il faut patienter |
500, 503 | erreur du serveur, ou service temporairement indisponible |
7.3Bien concevoir une API
Quelques règles font une API agréable et durable : des noms de ressources clairs et réguliers, au pluriel ; des réponses paginées, qui renvoient les longues listes par morceaux, avec un lien vers la page suivante ; des filtres passés en paramètres (/commandes?statut=livree) ; des messages d’erreur explicites, mais qui ne révèlent rien du fonctionnement interne ; un numéro de version dans l’adresse ou un en-tête ; et une conception qui part des besoins de ceux qui l’utiliseront, plutôt que de la structure de la base de données. Beaucoup d’API dites REST ne respectent qu’une partie des principes de Fielding ; l’essentiel est d’être cohérent et bien documenté.
Pour s’exercer
Exercice 1 : concevoir les adresses d’une API
Une médiathèque veut une API pour gérer son catalogue. Indiquez la méthode et l’adresse pour : a) lister les livres ; b) consulter le livre numéro 42 ; c) ajouter un livre ; d) corriger le titre du livre 42 ; e) retirer le livre 42 du catalogue. Quel code de réponse attendre en cas de succès pour c et e ?
Voir la réponse
a) GET /livres, avec pagination ; b) GET /livres/42 ; c) POST /livres, avec la description du livre en JSON dans le corps de la requête ; d) PATCH /livres/42, avec le seul champ modifié ; e) DELETE /livres/42. En cas de succès, c renvoie 201, ressource créée, généralement avec l’adresse du nouveau livre ; e renvoie 204, sans contenu. On n’écrit pas /ajouterLivre ou /supprimerLivre?id=42 : en REST, l’action est portée par la méthode, l’adresse ne désigne que la ressource.
Exercice 2 : interpréter les codes de réponse
Quel code une API bien conçue renvoie-t-elle dans chacun des cas suivants ? a) le jeton d’accès a expiré ; b) un client authentifié demande la facture d’un autre client ; c) une application interroge le service trente fois par seconde alors que son contrat en autorise dix ; d) la date fournie est « 31/02/2026 ».
Voir la réponse
a) 401 : l’identité n’est plus prouvée, l’application doit obtenir un nouveau jeton. b) 403, ou 404 si l’on préfère ne pas révéler l’existence de la facture ; en aucun cas 200 avec la facture (voir l’exercice 6). c) 429, accompagné si possible d’un en-tête Retry-After qui indique combien de temps attendre. d) 400, avec un message qui précise que la date est invalide.
Exercice 3 : de SOAP à REST
Réécrivez l’appel SOAP de la section 5.3 sous forme de requête REST. Que deviennent l’enveloppe et le fichier WSDL ?
Voir la réponse
La requête devient GET /v1/villes/lyon/previsions : la ville passe dans l’adresse de la ressource, l’opération « Prevision » est portée par la méthode GET, appliquée à la ressource « prévisions ». L’enveloppe disparaît : les informations techniques de l’en-tête SOAP, comme l’authentification, passent dans les en-têtes HTTP, et la réponse est un simple objet JSON. Le fichier WSDL est remplacé par une description OpenAPI. Le message tient en une ligne au lieu de sept, ce qui explique en bonne partie le succès de REST.
Exercice 4 : compatible ou non ?
Une API météo renvoie {"ville": "Lyon", "temp": 18}. Lesquelles de ces évolutions risquent de casser les applications existantes ? a) ajouter un champ "vent": 12 ; b) renommer temp en temperature ; c) renvoyer "18", une chaîne de caractères, au lieu du nombre 18 ; d) rendre obligatoire un nouveau paramètre pays ; e) ajouter une ressource /alertes.
Voir la réponse
a) et e) sont compatibles : les applications existantes ignorent le nouveau champ et n’appellent pas la nouvelle ressource, à condition d’avoir été écrites pour tolérer les champs inconnus. b), c) et d) sont incompatibles : une application qui lit temp ne trouve plus rien, une autre qui additionne des températures obtient une erreur ou concatène des textes, et toutes les requêtes sans pays sont rejetées. Ces changements imposent une nouvelle version majeure, /v2/, l’ancienne restant disponible pendant une période de transition annoncée. Pour d), on peut aussi rendre le paramètre facultatif, avec une valeur par défaut.
Exercice 5 : respecter un quota
Votre contrat avec un service de données boursières autorise 1 000 requêtes par heure. Votre script interroge le cours d’une action toutes les deux secondes. Que se passe-t-il, et au bout de combien de temps ? Comment faire mieux ?
Voir la réponse
Une requête toutes les deux secondes donne 1 800 requêtes par heure. Le quota de 1 000 est atteint après 1 000 × 2 = 2 000 secondes, soit environ 33 minutes ; les requêtes suivantes reçoivent le code 429 jusqu’au renouvellement du quota. Pour faire mieux : interroger moins souvent, une requête toutes les quatre secondes en donne 900 par heure ; demander plusieurs actions en une seule requête si l’API le permet ; garder en mémoire, en cache, les réponses qui changent peu ; utiliser un webhook ou un flux en temps réel si le service en propose ; et, en cas de code 429, attendre le délai indiqué au lieu de réessayer immédiatement, ce qui aggraverait la situation.
Exercice 6 : la commande du voisin
Connecté à votre compte sur une application de commerce, vous consultez votre commande à l’adresse /api/commandes/1042. Par curiosité, un utilisateur remplace 1042 par 1043 et obtient la commande d’un autre client, avec son nom et son adresse. Quel est le défaut ? Comment le corriger ?
Voir la réponse
L’API vérifie que l’utilisateur est connecté, mais pas que la commande demandée lui appartient : c’est un défaut de contrôle d’autorisation au niveau de chaque objet, la première faiblesse du classement de l’OWASP consacré aux API (voir le coin cyber). La correction se fait sur le serveur : à chaque requête, avant de renvoyer une commande, vérifier que son propriétaire est bien l’utilisateur identifié par le jeton, et répondre 403 ou 404 sinon. Utiliser des identifiants difficiles à deviner, plutôt que des numéros qui se suivent, complique l’exploitation mais ne remplace pas cette vérification. Des tests automatiques doivent la contrôler pour chaque ressource, et la surveillance doit repérer un utilisateur qui parcourt des centaines de numéros à la suite. Un tel défaut constitue en outre une violation de données personnelles, à signaler à la CNIL (Commission nationale de l’informatique et des libertés).
8Décrire, publier, gouverner
8.1OpenAPI, l’héritier de WSDL
REST ne prévoyait pas de format de description. La spécification OpenAPI, issue de l’outil Swagger et confiée en 2015 à un consortium hébergé par la Fondation Linux, a comblé ce manque : un fichier au format JSON, ou YAML, un format texte voisin plus facile à lire, décrit toutes les ressources d’une API, ses méthodes, ses paramètres, ses réponses et ses règles d’authentification. Comme WSDL autrefois, il permet de générer une documentation interactive, où l’on peut essayer les appels, du code client pour de nombreux langages, et des tests automatiques. Beaucoup d’équipes écrivent désormais ce contrat avant le code, une démarche dite « API d’abord ».
8.2Les passerelles d’API
Une organisation qui publie de nombreuses API les place généralement derrière une passerelle (en anglais API gateway), un point d’entrée unique qui vérifie l’identité des appelants, applique les quotas (un nombre maximal d’appels par minute ou par jour), transforme éventuellement les requêtes, met en cache les réponses fréquentes et journalise tous les appels. Elle fournit aussi un portail où les développeurs s’inscrivent, obtiennent leurs clés et consultent la documentation.
8.3L’économie des API
Les API sont devenues un modèle économique : on paie un service de cartographie, de paiement ou d’intelligence artificielle à l’appel ou par abonnement. Elles sont aussi un outil de politique publique. L’État français publie sur le site api.gouv.fr un catalogue de ses API, des adresses postales aux données des entreprises, et ses administrations échangent des informations par API pour éviter de redemander aux usagers des justificatifs qu’elles détiennent déjà. En Europe, la deuxième directive sur les services de paiement, dite DSP2, adoptée en 2015, a obligé les banques à ouvrir à des prestataires agréés, avec l’accord du client, des API d’accès aux comptes, ce qui a permis l’essor des applications d’agrégation de comptes et de paiement.
9Au-delà de RESTApprofondir
REST n’est pas la seule façon de concevoir une API distante. Plusieurs styles coexistent, chacun adapté à certains usages (tableau 3) :
- GraphQL, créé par Facebook pour ses applications mobiles et publié en 2015, offre une adresse unique à laquelle le client envoie une requête qui décrit exactement les données voulues, champ par champ, éventuellement réparties entre plusieurs ressources ; il évite ainsi de multiplier les appels ou de recevoir des données inutiles ;
- gRPC, publié par Google en 2015, renoue avec l’appel de procédure à distance, mais avec des messages binaires compacts, décrits dans le format Protocol Buffers, et le protocole HTTP/2 ; très efficace, il est surtout utilisé entre microservices, à l’intérieur d’un centre de données ;
- les webhooks inversent le sens de l’appel : au lieu d’interroger régulièrement un service pour savoir si quelque chose a changé, on lui donne une adresse qu’il appellera lui-même lorsqu’un événement se produit, par exemple la confirmation d’un paiement ;
- les WebSockets ouvrent une connexion permanente dans les deux sens entre un navigateur et un serveur, pour les messageries, les jeux ou les tableaux de bord en temps réel (voir les sockets).
| Style | Apparition | Format des messages | Usage typique |
|---|---|---|---|
| XML-RPC | 1998 | XML | pour mémoire ; anciens outils de publication |
| SOAP | 1998-2003 | XML, enveloppe normalisée | systèmes d’entreprise des années 2000, banques, administrations |
| REST | 2000 | JSON le plus souvent | API publiques, applications Web et mobiles |
| GraphQL | 2015 | JSON | applications aux besoins de données variés |
| gRPC | 2015 | binaire | communication interne entre microservices |