REST est le principe architectural sous-jacent du Web. La chose étonnante sur le Web est le fait que les clients (navigateurs) et les serveurs peuvent interagir de manière complexe sans que le client ne sache quoi que ce soit au préalable sur le serveur et les ressources qu'il héberge. La principale contrainte est que le serveur et le client doivent tous deux s'accorder sur le support utilisé, qui dans le cas du Web est HTML .
Une API qui adhère aux principes de REST n'exige pas que le client sache quoi que ce soit sur la structure de l'API. Le serveur doit plutôt fournir toutes les informations dont le client a besoin pour interagir avec le service. Un formulaire HTML en est un exemple: le serveur spécifie l'emplacement de la ressource et les champs obligatoires. Le navigateur ne sait pas à l'avance où soumettre les informations et il ne sait pas à l'avance quelles informations soumettre. Les deux formes d'informations sont entièrement fournies par le serveur. (Ce principe est appelé HATEOAS : Hypermedia As The Engine Of Application State .)
Alors, comment cela s'applique-t-il à HTTP et comment peut-il être mis en œuvre dans la pratique? HTTP est orienté autour des verbes et des ressources. Les deux verbes d'usage courant sont GETet POST, que je pense que tout le monde reconnaîtra. Cependant, la norme HTTP en définit plusieurs autres comme PUTet DELETE. Ces verbes sont ensuite appliqués aux ressources, selon les instructions fournies par le serveur.
Par exemple, imaginons que nous avons une base de données d'utilisateurs gérée par un service Web. Notre service utilise un hypermédia personnalisé basé sur JSON, pour lequel nous attribuons le type MIME application/json+userdb(il peut également y avoir un application/xml+userdbet application/whatever+userdb- de nombreux types de supports peuvent être pris en charge). Le client et le serveur ont tous deux été programmés pour comprendre ce format, mais ils ne se connaissent pas. Comme le souligne Roy Fielding :
Une API REST doit consacrer presque tout son effort descriptif à définir le ou les types de média utilisés pour représenter les ressources et piloter l'état de l'application, ou à définir des noms de relation étendus et / ou un balisage hypertexte pour les types de média standard existants.
Une demande pour la ressource de base / peut renvoyer quelque chose comme ceci:
Demande
GET /
Accept: application/json+userdb
Réponse
200 OK
Content-Type: application/json+userdb
{
"version": "1.0",
"links": [
{
"href": "/user",
"rel": "list",
"method": "GET"
},
{
"href": "/user",
"rel": "create",
"method": "POST"
}
]
}
Nous savons de la description de nos médias que nous pouvons trouver des informations sur les ressources connexes dans les sections appelées "liens". C'est ce qu'on appelle les contrôles Hypermedia . Dans ce cas, nous pouvons dire à partir d'une telle section que nous pouvons trouver une liste d'utilisateurs en faisant une autre demande de/user :
Demande
GET /user
Accept: application/json+userdb
Réponse
200 OK
Content-Type: application/json+userdb
{
"users": [
{
"id": 1,
"name": "Emil",
"country: "Sweden",
"links": [
{
"href": "/user/1",
"rel": "self",
"method": "GET"
},
{
"href": "/user/1",
"rel": "edit",
"method": "PUT"
},
{
"href": "/user/1",
"rel": "delete",
"method": "DELETE"
}
]
},
{
"id": 2,
"name": "Adam",
"country: "Scotland",
"links": [
{
"href": "/user/2",
"rel": "self",
"method": "GET"
},
{
"href": "/user/2",
"rel": "edit",
"method": "PUT"
},
{
"href": "/user/2",
"rel": "delete",
"method": "DELETE"
}
]
}
],
"links": [
{
"href": "/user",
"rel": "create",
"method": "POST"
}
]
}
Nous pouvons en dire beaucoup de cette réponse. Par exemple, nous savons maintenant que nous pouvons créer un nouvel utilisateur par POSTING /user:
Demande
POST /user
Accept: application/json+userdb
Content-Type: application/json+userdb
{
"name": "Karl",
"country": "Austria"
}
Réponse
201 Created
Content-Type: application/json+userdb
{
"user": {
"id": 3,
"name": "Karl",
"country": "Austria",
"links": [
{
"href": "/user/3",
"rel": "self",
"method": "GET"
},
{
"href": "/user/3",
"rel": "edit",
"method": "PUT"
},
{
"href": "/user/3",
"rel": "delete",
"method": "DELETE"
}
]
},
"links": {
"href": "/user",
"rel": "list",
"method": "GET"
}
}
Nous savons également que nous pouvons modifier les données existantes:
Demande
PUT /user/1
Accept: application/json+userdb
Content-Type: application/json+userdb
{
"name": "Emil",
"country": "Bhutan"
}
Réponse
200 OK
Content-Type: application/json+userdb
{
"user": {
"id": 1,
"name": "Emil",
"country": "Bhutan",
"links": [
{
"href": "/user/1",
"rel": "self",
"method": "GET"
},
{
"href": "/user/1",
"rel": "edit",
"method": "PUT"
},
{
"href": "/user/1",
"rel": "delete",
"method": "DELETE"
}
]
},
"links": {
"href": "/user",
"rel": "list",
"method": "GET"
}
}
Notez que nous utilisons différents verbes HTTP ( GET, PUT, POST, DELETEetc.) pour manipuler ces ressources, et que la seule connaissance que nous présumons de la part du client est notre définition de médias.
Lectures complémentaires:
(Cette réponse a fait l'objet de nombreuses critiques pour avoir manqué le point. Pour l'essentiel, cette critique a été juste. Ce que j'ai décrit à l'origine correspondait davantage à la façon dont REST était généralement mis en œuvre il y a quelques années a d'abord écrit ceci, plutôt que sa vraie signification. J'ai révisé la réponse pour mieux représenter la vraie signification.)
