Services web et API REST
Sommaire
Comment deux applications échangent des données, indépendamment de leur plateforme et de leur langage.
1. Service web, API, REST
- Un service web est un élément de logique applicative permettant l'interopérabilité entre applications. Il leur permet de communiquer et de partager données et fonctionnalités, indépendamment de la plateforme ou des technologies utilisées.
- Une API (Application Programming Interface) est une interface qui expose un ensemble de fonctionnalités utilisables par d'autres applications (les consommateurs). Elle facilite la réutilisation de composants existants.
- REST (Representational State Transfer) est un type d'architecture qui propose de représenter le modèle de données et les services sous forme de ressources accessibles depuis une URL, via les méthodes standard du protocole HTTP.
Principe général : un serveur expose des données et des services ; une application cliente les consomme via HTTP(S). Les données échangées sont formatées dans un standard, généralement JSON ou XML.
2. La ressource REST
Une ressource REST se compose de :
- une URI (Uniform Resource Identifier) : elle représente une ressource unique sur le serveur ;
- un verbe HTTP : il identifie l'opération à réaliser ;
- un en-tête HTTP : format du contenu, jeton d'authentification… ;
- des paramètres de requête : filtres, tri, pagination ;
- une réponse HTTP : code de retour et contenu.
Convention d'URI : un nom de ressource au pluriel, pas de verbe.
/api/v1/books plutôt que /api/getAllBooks — c'est le verbe HTTP qui porte
l'action.
3. La requête HTTP
Les verbes HTTP correspondent aux opérations CRUD :
| Verbe | Opération | CRUD |
|---|---|---|
GET | Récupérer une ressource | Read |
POST | Créer une ressource (données dans le body) | Create |
PUT / PATCH | Mettre à jour une ressource existante | Update |
DELETE | Supprimer une ressource | Delete |
PUT remplace la ressource entière, PATCH n'en modifie qu'une partie.
En-têtes courants
| En-tête | Rôle |
|---|---|
Accept | Format(s) de réponse acceptés (application/json, application/xml) |
Content-Type | Format des données contenues dans le corps de la requête |
Authorization | Informations d'identification pour l'authentification |
Paramètres de requête
Informations envoyées via l'URL sous forme de couples CLE=VALEUR placés après un ?
et séparés par des &.
GET http://library.demo.local/api/v1/books?genre=policier&tri=titre&page=24. La réponse HTTP
| Famille | Sens | Codes fréquents |
|---|---|---|
| 1xx | Information | — |
| 2xx | Succès | 200 OK (GET réussi), 201 Created (POST, ressource créée), 204 No Content |
| 3xx | Redirection | 301, 304 Not Modified |
| 4xx | Erreur côté client | 400 Bad Request (syntaxe invalide), 401 Unauthorized (authentification invalide), 403 Forbidden (accès interdit), 404 Not Found |
| 5xx | Erreur côté serveur | 500 Internal Server Error |
Distinction souvent demandée : 401 signifie « je ne sais pas qui tu es » —
authentification manquante ou invalide. 403 signifie « je sais qui tu es, mais tu n'as pas le
droit » — c'est un problème d'autorisation. La même différence qu'entre authentification et habilitation.
5. Le format JSON
JSON (JavaScript Object Notation) est un format léger d'échange de données, facile à lire et à interpréter par des traitements informatiques.
- Objet : ensemble non ordonné de paires clé/valeur. Il commence par
{et se termine par}. La clé est suivie de:puis de la valeur ; les couples sont séparés par des virgules. - Tableau : ensemble ordonné de valeurs, entre
[et], séparées par des virgules. - Une valeur peut être une chaîne entre guillemets, un nombre,
true,false,null, un objet ou un tableau. Ces structures peuvent être imbriquées.
{
"id": 12,
"titre": "L'Étranger",
"auteur": {
"nom": "Camus",
"prenom": "Albert"
},
"genres": ["roman", "philosophie"],
"disponible": true,
"emprunteur": null
}Les clés sont toujours entre guillemets doubles, et une virgule finale après le dernier élément est interdite — ce sont les deux erreurs de syntaxe les plus courantes.
6. Types d'API et documentation
| Type | Description |
|---|---|
| API privée | Réservée à un usage interne : elle permet la communication entre les composants du SI de l'organisation |
| API partenaire | Permet d'enrichir une application avec des fonctionnalités de partenaires externes, souvent avec une tarification selon le volume : paiement en ligne, cartographie, réseaux sociaux |
| API publique | API Open Data : données libres, gratuites et sans restriction majeure |
Chaque API est accompagnée d'une documentation qui décrit son objectif, la politique d'utilisation (sécurité, mécanisme d'authentification, quotas), les endpoints (URI, actions possibles, formats, paramètres), des exemples de requêtes et de réponses copiables, et des exemples de code dans différents langages.
Des outils génèrent cette documentation automatiquement : Swagger / OpenAPI, ApiDoc.
7. Sécurité des API
Objectif : contrôler l'accès et garantir la confidentialité des données, via des mécanismes d'authentification, d'autorisation et de gestion des quotas.
| Mécanisme | Principe | Limite |
|---|---|---|
| API Key | Chaîne alphanumérique unique générée par le fournisseur, fournie à chaque requête. Permet de gérer des quotas. | Ne permet pas de distinguer les utilisateurs individuels ; si la clé fuite, tout l'accès est compromis |
| Basic Auth | Login et mot de passe transmis dans l'en-tête de la requête | Identifiants envoyés à chaque appel : inutilisable sans HTTPS |
| Bearer Token | Un serveur d'authentification génère un jeton attestant l'identité et les autorisations. Il est fourni dans l'en-tête de chaque requête. | — c'est le mécanisme recommandé : le jeton peut expirer ou être révoqué |
Quel que soit le mécanisme, une API se consomme en HTTPS : sans chiffrement du transport, clé, identifiants ou jeton circulent en clair et sont interceptables.
8. Tester et créer une API
Avant d'intégrer une API dans une application, il est primordial de voir comment elle fonctionne :
- directement sur le portail de l'API, qui offre parfois une interface d'exécution (try it out) ;
- Postman : outil graphique pour construire et exécuter des requêtes HTTP ;
- cURL : outil en ligne de commande, qui prend en charge HTTP, FTP, TELNET, SMTP…
curl -X GET "https://swapi.dev/api/people/1/" -H "Accept: application/json"
curl -X POST "http://library.demo.local/api/v1/books" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{"titre":"L Etranger","auteur":"Camus"}'Pour créer une API, le développeur peut utiliser différents langages (JavaScript, PHP…) et des frameworks orientés API : API Platform, Express.js, Django REST Framework.