Ce document présente les fondamentaux d'une API REST, définissant ses objectifs, son architecture et ses contraintes, notamment la séparation client-serveur et l'État sans état. Il décrit également les éléments clés des requêtes et réponses HTTP, ainsi que les méthodes utilisées pour interagir avec les ressources. Enfin, il aborde les codes de statut HTTP et leur signification dans le contexte des APIs.

1. Fondamentaux d’une
API REST
M. Abdoulaye DIENG Avril 2020

2. Objectif général
Connaître les fondamentaux d’une API REST

3. Objectifs spécifiques
• Savoir définir une API
• Connaître l’architecture REST
• Connaître les contraintes du REST
• Connaître la structure d’une requêtes HTTP
• Connaître les caractéristiques d’une ressources
• Se servir des méthodes HTTP
• Connaître la structure d’une réponses HTTP
• Connaître les codes HTTP

4. Sommaire
1) API
2) REST
3) Contraintes REST
4) Requêtes HTTP
5) Ressources
6) Méthodes
7) Réponses
8) Codes HTTP

5. API
• Pb : après avoir réalisé une e-boutique, un développeur
souhaite ajouter la possibilité de payer en ligne
• Sol : intégrer un système extérieur comme Paypal ou
PayDunya
• API (Application Programming Interface) : ensemble
normalisé de classes, de méthodes, de fonctions et
de constantes qui sert de façade par laquelle un logiciel offre
des services à d'autres logiciels (Wikipedia nov. 2019)
• Exemples
PayPal API, PayDunya API, Google Maps API, Twitter API,
Youtube API, Facebook API

6. REST
• REST : Representational State Transfer
• Architecture orientée ressources pour les systèmes
distribués
• Créé par Roy Fielding, auteur de la spécification HTTP,
développeur du serveur Web Apache, …
• L’architecture REST utilise les spécifications originelles
du protocole HTTP, plutôt que de réinventer une surcouche
(comme le font SOAP ou XML-RPC par exemple).

7. Contraintes REST
• Client-Server
séparation de rôles entre client (application web ou
application mobile) et serveur (API REST)
• Stateless Server
oLe serveur doit être capable de comprendre chaque
requête sans faire appel à des données de session
oLe client doit conserver les informations sur son état
(sous forme de token par exemple) et les joindre à
chaque requête
• Cache
oToute réponse peut être notées comme « cachables »
grâce aux en-têtes HTTP correspondantes
oCe qui permettra à un serveur proxy ou à un client de
renvoyer une même ressource

8. Contraintes REST
• Uniform interface
oIdentification des ressources : URI
oReprésentation des ressources : JSON et XML par exemple
oauto-description des réponses avec l’URI sollicitée, la
méthode d'appel, le code HTTP et le format des données
oHypermedia : la réponse décrit la manière de naviguer à
travers le service pour effectuer d’autres requêtes
• Layered System
Possibilité d’ajouter des couches intermédiaires (proxy
server, firewall, CDN, etc …) transparentes au client
• Code-on-Demand (optionnelle)
le client peut demander au serveur du code (applet java ou
script javaScript) à exécuter

9. Requêtes HTTP
• Une requête HTTP émane d'un client (tout logiciel ayant la
capacité de forger une requête).
• Une requête est constituée des éléments suivants :
oLa première ligne (request line) doit contenir :
 la méthode HTTP (GET, POST, PUT, DELETE , …)
 l'URI : contenant la ressource (exemple : /lutteurs/1 )
 la version du protocole (exemple : HTTP/1.1 )
oLes entêtes (headers), une entête par ligne, chaque ligne
finie par le caractère spécial "retour à la ligne" (CRLF)
oLe contenu de la requête (body), doit être séparé de deux
caractères spéciaux "retour à la ligne"

10. Les requêtes - exemple
Exemple de requête POST :
POST /lutteurs HTTP/1.1
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) …
Content-Type: application/x-www-form-urlencoded
Content-Length: 30
id=1&pseudo=Modou Lo&poids=110

11. Ressources
• Une ressource est un objet auquel les utilisateurs d’une API
peuvent vouloir accéder.
Ex : utilisateur, produit, article, lutteur
• Collection = ensemble de ressources du même type
Ex : utilisateurs, produits, articles, commentaires, lutteurs
• URI : identifiant d’une ressource ou d’une collection
o Ex 1 : /articles identifie la collection « articles »
o Ex 2 : /articles/1 identifie l’article numéro 1
oEx 3 : /articles/1/commentaires identifie les
commentaires sur l’article numéro 1
• Principales représentation d’une ressource : JSON et XML
Exemple en JSON :
"lutteurs": [
{ "id": 1, "pseudo": "Modou Lo", "poids": 110 },
{ "id": 2, "pseudo": "Yawou Diaal", "poids": 70 }
]

12. Méthodes
• Méthode : action que l'on souhaite réaliser sur la ressource
demandée
• Quelques méthodes (ou verbes) HTTP
oGET : récupère une ou +sieurs ressource(s)
oPOST : crée une ressource
oPUT : remplace entièrement ou ajoute une ressource
oPATCH : remplace partiellement une ressource
oDELETE : supprime une ressource
oOPTIONS : obtient la liste des actions possibles pour
une ressource donnée

13. Réponses HTTP
• Une réponse HTTP émane d'un serveur (tout logiciel ayant
la capacité de forger une réponse HTTP)
• Une réponse est constituée des éléments suivants :
oLa première ligne (status line) doit contenir :
 la version du protocole utilisée
 le code d’état (à voir)
 l'équivalent textuel du code d’état
oLes entêtes (headers), une entête par ligne, chaque ligne
finie par le caractère spécial "retour à la ligne" (CRLF)
oLe contenu de la réponse (body), doit être séparé de
deux caractères spéciaux "retour à la ligne"

14. Réponses HTTP - exemple
HTTP/1.1 200 OK
Date: Sat, 09 Nov 2019 10:40:28 GMT
Content-Type: application/json
{
"id": 1, "pseudo": "Modou Lo", "poids": 110
}

15. Codes HTTP
https://www.illustradata.com/api-rest/
Code d’état : permet de déterminer le résultat d'une requête ou
d'indiquer une erreur au client