1. Zaghir Y Rest Page 1 sur 17
Table des matières
Protocole http :................................................................................................................................... 2
Requête et réponse HTTP............................................................................................................... 3
Envoi d’un formulaire..................................................................................................................... 4
Cookies............................................................................................................................................ 6
Réinitialisation d’un formulaire ..................................................................................................... 7
Requête d’une image et réponse................................................................................................... 8
Méthodes HTTP............................................................................................................................... 9
a. Nouvelle ressource sans URL.................................................................................................... 12
b. Nouvelle ressource avec une URL ............................................................................................ 12
c. Pas de nouvelle ressource......................................................................................................... 12
4. PUT et PATCH............................................................................................................................ 12
a. PUT ............................................................................................................................................ 12
b. PATCH........................................................................................................................................ 13
5. LINK et UNLINK ......................................................................................................................... 13
6. DELETE....................................................................................................................................... 14
Une programmation statless ou statful........................................................................................... 14
Liens vers les ressources................................................................................................................... 15
1. Action sur l’ensemble des ressources d’un type ..................................................................... 15
2. Action sur une ressource donnée............................................................................................. 15
3. Action sur une ressource liée ................................................................................................... 15
4. Format de retour ...................................................................................................................... 16
2. Zaghir Y Rest Page 2 sur 17
RestFull
Faits le 02/05/2016
Version
Outils de debug chrome
Protocole http :
HTTP : HyperText Tranfert Protocol
Protocole qui permet au client de récupérer des documents du serveur
Ces documents peuvent être statiques (contenu qui ne change pas :
HTML, PDF, Image, etc..) Ou dynamiques (Contenu généré dynamiquement au moment de la
requête : PHP, JSP, ASP…)
Ce protocole permet également de soumissionner les formulaires
Fonctionnement (très simple en HTTP/1.0)
Le client se connecte au serveur (Créer une socket)
Le client demande au serveur un document : Requête HTTP
Le serveur renvoi au client le document (status=200) ou d’une erreur(status=404 quand le
document n’existe pas)
Déconnexion
Un serveur Web est un ordinateur qui accepte des demandes, appelées requêtes, envoyées par ses
clients généralement sur le port 80 et qui leur expédie en réponse des pages Web, contenus de
fichiers .htm ou .html stockés sur son disque. Un utilisateur peut évidemment utiliser Telnet pour se
connecter à un serveur Web, mais il emploiera plus probablement un client spécialisé, qui est un
navigateur Web. Les requêtes et réponses Web respectent le protocole du Web, le protocole HTTP ;
comme les réponses POP3, elles sont constituées de texte, mais à la différence de POP3, la
connexion HTTP est close par le serveur dès l’envoi de sa réponse : si le client a ensuite besoin d’une
autre page du même serveur, il ouvrira une nouvelle connexion.
Chaque page Web a un identifiant Web, appelé URL, qui se compose d’un nom de site fréquemment
de la forme www.xxxx.yyy et du nom de son fichier .htm ou .html. Pour obtenir une page Web du
serveur, le navigateur écrit dans sa requête l’URL de cette page ; par exemple :
GET http://www.sciencesnat.com/connect.htm HTTP/1.0
Dans sa réponse, le serveur fournit la page, autrement dit le contenu du fichier demandé. Celle-ci
n’est pas du texte libre, mais elle est rédigée selon des règles définies par le protocole HTML. Ce
protocole structure l’information de la page à l’intérieur de balises <html>, <body>, <...> tel que dans
l’exemple suivant.
3. Zaghir Y Rest Page 3 sur 17
<html>
<body>
<form method="GET" action="Connexion">
Nom :<input name="nom"><br> Mot de passe : <input
name="password"><br> <input type="submit" value="Ok">
<input type="reset" value="Remise à 0">
</form>
</body>
</html>
Lorsque le navigateur reçoit cette page HTML en provenance du serveur Web, il convertit ses
balises en composants graphiques qu’il affiche dans sa fenêtre :
La balise <form> est devenue un cadre, appelé formulaire. Ce cadre contient deux champs de
saisie, les champs de formulaire, et aussi deux boutons
Requête et réponse HTTP
Les requêtes et réponses HTTP sont plus complexes que celles prises en exemples ci-dessus. Elles
sont constituées d’un en-tête et d’un corps éventuellement vide ; si le corps n’est pas vide, alors il
est séparé de l’en-tête par une ligne vide. L’exemple ci-dessous présente une requête HTTP sans
corps et qui dans trois lignes de texte successives :
1) demande la page www.sciencesnat.com/connect.htm au moyen de la version 1.0 du
protocole http
2) indique qu’elle attend du code HTML
3) déclare que le navigateur qui l’a émise est un navigateur Mozilla.
GET http://www.sciencesnat.com/connect.htm HTTP/1.0
Accept : text/html
User-Agent : Mozilla/4.0 (compatible; MSIE 5.0; Windows 95)
4. Zaghir Y Rest Page 4 sur 17
La réponse HTTP du serveur à cette requête contient à la fois un en-tête et un corps, qui est
une page HTML :
<html>
<body>
<form method="GET" action="Connexion">
Nom :<input name="nom"><br> Mot de passe : <input
name="password"><br> <input type="submit" value="Ok">
<input type="reset" value="Remise à 0">
</form>
</body>
</html>
Envoi d’un formulaire
Lorsque le navigateur analyse la réponse HTTP ci-dessus, il constate qu’il a bien reçu du texte HTML.
Il affiche dans sa fenêtre la conversion de ce texte en composants graphiques comme déjà montré ci-
dessus. L’utilisateur (-trice) peut alors effectuer des saisies :
Code Signification
200 la réponse contient bien la page HTML demandée
400 la requête qui a été envoyée est syntaxiquement incorrecte (ne respecte pas
le protocole HTTP)
404 la page demandée n’a pu être trouvée
500 le serveur a rencontré une erreur interne
302 l’URL est temporairement indisponible
Nom Commentaire sur la valeur
Server la réponse HTTP est envoyée par un serveur Web IIS
Date la réponse HTTP a été envoyée le 02/09/2010
Content-Type
Content-Lentgh
Last-Modified
le corps de la réponse HTTP contient du texte : une page
HTML ; cette page a été dernièrement modifiée le 2 juin
2006 et comporte 257 caractères
HTTP/1.0 200 OK
Date : Sat, 2 Sep 2010 14:37:12 GMT
Server : Microsoft-IIS/2.0
Content-Type : text/HTML
Content-Lentgh : 257
Last-Modified : SUN, 02 Jun 2009 08:25:13 GMT
Entête
HTTP
Dans l’en-tête de la réponse, La première ligne indique
toujours la version du protocole HTTP, suivie d’un code
d’erreur et d’un commentaire optionnel. Les codes d’erreurs
sont les suivants
Les lignes suivantes contiennent des
paramètres d’en-tête. Chacune est composée
du nom du paramètre suivi de sa valeur
5. Zaghir Y Rest Page 5 sur 17
L’utilisatrice clique ensuite sur le bouton Ok. Le protocole HTML prévoit que lorsqu’un bouton de
type "submit" est cliqué, le navigateur :
construit une requête HTTP qui contient les informations saisies dans le formulaire auquel
appartient le bouton, chacune précédée du nom de son champ de saisie
arrange littéralement ces informations selon la valeur GET ou POST de l’attribut méthode du
formulaire ;
envoie cette requête à l’URL spécifiée par l’attribut action du formulaire.
En méthode GET, les informations saisies sont ajoutées à la suite de l’URL après un caractère ? et
séparés par des & :
GET http://www.sciencesnat.com/Connexion?name=anne&password=ange
HTTP/1.0
Accept: text/html
User-Agent: Mozilla/4.0 (compatible; MSIE 5.0; Windows 95)
En méthode POST, le navigateur place les informations saisies dans le corps de la requête :
POST http://www.sciencesnat.com/Connexion HTTP/1.0
Accept: text/html
User-Agent : Mozilla/4.0 (compatible; MSIE 5.0; Windows 95)
*** saut de ligne ***
GET / Nom_Script http ?login=val1&pass=val1&… HTTP/1.0
Accept : text/html
Accept-Language :fr
User-Agent : Mozilla/4.0
Corps de la requête est vide
Entête de la requête envoyée
par le client de type GET
POST / Nom_Script HTTP/1.0
Accept : text/html
Accept-Language :fr
User-Agent : Mozilla/4.0
*** saut de ligne ***
login=Value1&passe=Value2&V
ar3=Value3
Entête de la requête envoyée
par le client de type POST
Corps de la requête
6. Zaghir Y Rest Page 6 sur 17
Cookies
Nous supposons que le serveur, après réception de la requête HTTP d’authentification ci-dessus, juge
que le mot de passe "ange" s’accorde bien avec le nom "anne". Il retourne donc une réponse HTTP
constituée d’une page HTML de bienvenue, qui contient une devinette ainsi qu’une image :
Réponse HTTP :
<html>
<body>
<form method="POST" action="Question">
Combien voyez-vous de couleurs dans cette image ?<br>
<img src="chien.gif"> <input name="color">
<input type="submit" value="Ok">
<input type="reset" value="Remise à 0">
</form>
</body>
</html>
Entête de la réponse retournée
par le serveur
HTTP/1.0 200 OK
Date : Wed, 12May16 10 :50 :01 GMT
Server : Apache/1.3.25
Last-Modified: Wed, 12May16 18 :48 :01 GMT
Content-Type :Text/html
Content-length :4205
*** saut de ligne ***
<HTML><HEAD>…..
<BODY>
….
</BODY>
</HTML>
Corps de la requête
Ligne de Status
Date du serveur
Non de serveur
Dernière modification
Type de contenu
Sa taille
Le fichier que le
client va afficher
Server: Microsoft-IIS/2.0
Content-Type: text/HTML
Set-Cookie: jsessionid=RRTY56JK142HJE
7. Zaghir Y Rest Page 7 sur 17
Dans le navigateur :
Dans l’en-tête apparaît un paramètre Set-Cookie : le serveur envoie ce paramètre lorsqu’il désire que
sa valeur, qui est significative pour lui, soit conservée par le navigateur. Lorsque le navigateur lit la
réponse HTTP et qu’il rencontre un tel paramètre, il écrit dans un fichier la précieuse valeur ; ce
fichier a généralement pour nom le nom de l’utilisateur concaténé à l’URL du site, donc dans notre
exemple :
Désormais, dès que l’utilisatrice Anne envoie une nouvelle requête HTTP au site
www.sciencesnat.com, le navigateur inclut dans cette requête le ou les cookie(s) stocké(s) dans le
fichier anne@www.sciencesnat.com. Par exemple, si l’utilisatrice Anne valide son choix de 7, le
navigateur envoie la requête HTTP :
Réinitialisation d’un formulaire
Lorsqu’un bouton de type "reset" est cliqué, le navigateur remet à vide tous les champs du
formulaire auquel appartient le bouton. Dans la page HTML ci-dessus, l’utilisatrice Anne remet à vide
le seul champ de nom color :
POST http://www.sciencesnat.com/Question HTTP/1.0
Accept : text/html
User-Agent : Mozilla/4.0 (compatible; MSIE 5.0; Windows 95)
Cookie: jsessionid=RRTY56JK142HJE
color=7
Post :
Dans le corps de la page
8. Zaghir Y Rest Page 8 sur 17
Si ensuite elle clique le bouton Ok pour soumettre son formulaire au serveur, la requête HTTP
envoyée est :
L’élément color est supprimé de corps de la page après un rest
En effet, le navigateur envoie seulement les champs de formulaire qui sont renseignés. Ici aucun
champ n’étant renseigné, le corps de la requête est vide.
Requête d’une image et réponse
La page HTML précédente contient une image lorsque le navigateur lit la page Web dans la réponse
HTTP et qu’il rencontre la balise <img src="chien.gif>, il demande au serveur de lui fournir le contenu
du fichier chien.gif, par la requête HTTP suivante :
POST http://www.sciencesnat.com/Question HTTP/1.0
Accept : text/html
User-Agent : Mozilla/4.0 (compatible; MSIE 5.0; Windows 95)
Cookie: jsessionid=RRTY56JK142HJE
GET http://www.sciencesnat.com/chien.gif HTTP/1.0
Accept : image/gif
User-Agent : Mozilla/4.0 (compatible; MSIE 5.0; Windows 95)
En réponse, le serveur lui expédie l’image codée en texte :
HTTP/1.0 200 OK
Content-Type : image/GIF
Content-Lentgh : 396
Last-Modified : WED, 05 Dec 2008 9:13:20 GMT
76010000424D7601000000000000760000002800000020000000100000000100
04000000000000010000C40E0000C40E00001000000000000000000000000000
80000080000000808000800000008000800080800000C0C0C000808080000000
FF0000FF000000FFFF00FF000000FF00FF00FFFF0000FFFFFF0077777777775D
7E4777F8777E4777E47F8777F87E4777777E67E666E6666477777F8777F77772
877777E477E66666E6666477777F8777F7777877777E47777E666E4777777771
9. Zaghir Y Rest Page 9 sur 17
L’image présente dans la fenêtre du navigateur est le résultat de la conversion du corps de la réponse
HTTP ci-dessus en couleurs de pixels.
Méthodes HTTP
Tout développeur ou intégrateur web connaît deux méthodes HTTP, à savoir GET et POST.
Dans l’usage courant des formulaires, les informations transmises avec la méthode par défaut (GET)
passent en clair et sont visibles dans la barre d’adresse du navigateur, dans ce qu’on appelle la query
string, tandis que les paramètres transmis avec un formulaire en précisant la méthode POST ne
transparaissent pas dans la barre d’adresse, ni dans les logs Apache.
Une légende plaide dans le sens de l’utilisation de la méthode POST car la méthode GET serait limitée
à 255 caractères, incluant la taille de la query string. La spécification RFC 2616 n’indique aucune
exigence en ce sens.
Dans les faits, deux outils peuvent être à la source d’une éventuelle limitation, le navigateur utilisé et
le serveur répondant à la requête.
Côté navigateur, même Internet Explorer, dont les anciennes versions ont souvent mauvaise
réputation, de la version 4.0 édition 128 bits à la version 8, ne bride pas la taille de l’URL (Uniform
Resource Locator) à 256 caractères mais à 2 083 caractères.
128 bits correspond au niveau de chiffrement du navigateur et non des performances de la machine
et de son système d’exploitation.
Côté serveur, par défaut, le serveur Apache a une limitation par défaut à 8 190 octets, limitation qui
peut être abaissée au choix de l’administrateur système.
La légende tient certainement sa source de la RFC 3986 qui indique que les programmes qui
produisent des URI (Unifome Resource Identifier) devraient si possible se limiter à 255 caractères, et
à une syntaxe conforme à la syntaxe DNS (Domain Name System).
Il n’existe non pas deux mais onze méthodes HTTP, à savoir OPTIONS, HEAD, GET, POST, PUT, PATCH,
DELETE, LINK, UNLINK, TRACE et CONNECT. Chaque méthode est liée à un usage spécifique.
Elles vont être détaillées dans les sections suivantes, à l’exception des méthodes TRACE et CONNECT,
qui, mal utilisées, peuvent entraîner des failles de sécurité.
S’il fallait réduire les fonctionnalités des méthodes HTTP en une phrase, cela serait :
OPTIONS : déterminer les méthodes que sait traiter le serveur.
HEAD : déterminer les en-têtes d’une ressource.
GET : récupérer une ressource.
POST : créer une ressource.
PUT : créer ou modifier une ressource avec transmission de la ressource dans son intégralité.
PATCH : modifier une ressource avec transmission partielle de la ressource.
DELETE : supprimer une ressource.
Il est à noter que les méthodes les plus couramment utilisées sont GET, POST, PUT et DELETE.
1. OPTIONS
OPTIONS, peu exploitée, est la méthode d’entrée, celle qui permet de savoir à quelles méthodes va
répondre le serveur.
Deux possibilités s’offrent, soit demander globalement les méthodes autorisées sur l’ensemble des
ressources grâce à l’utilisation d’un astérisque, soit demander spécifiquement les méthodes
autorisées sur une ressource précise.
L’usage d’un astérisque permet généralement de faire une forme de ping sur le serveur.
OPTIONS * HTTP/1.1
OPTIONS /maRessource
HTTP/1.1
10. Zaghir Y Rest Page 10 sur 17
En retour, le serveur doit indiquer, avec un code HTTP 200, la liste des méthodes autorisées dans
l’en-tête Allow.
De manière naturelle, il n’y a pas lieu d’ajouter un corps à la réponse. Cependant, si un corps de
réponse est non vide, la norme impose d’indiquer l’en-tête Content-Length et il est logique
d’indiquer de même Content-Type.
2. HEAD et GET
La méthode GET est utilisée afin de récupérer une ressource, à la lire sans la modifier.
Les méthodes HEAD et GET sont identiques au détail près qu’une méthode GET contient un corps de
réponse, tandis que la méthode HEAD n’en contient pas.
La méthode HEAD permet donc de savoir si une ressource a été récemment modifiée.
Voici l’en-tête retourné par la réponse.
Le corps de la réponse est composé du code HTML de la page /maRessource.
En complément, la méthode GET peut être conditionnelle (conditional GET) ou partielle (partial GET).
a. Partial GET
Si un document récupéré à l’aide d’une méthode GET est volumineux, il peut être intéressant de le
récupérer en plusieurs fois.
Il faut pour cela que le serveur distant indique accepter les requêtes partielles. Il transmet pour cela
un en-tête Accept-Range, avec l’unité permettant de découper la ressource.
Seule l’unité bytes (octets) est définie dans le protocole HTTP/1.1.
Dans l’exemple ci-dessous, l’appel en méthode HEAD ou en méthode GET d’une ressource au format
PDF (Portable Document Format) d’environ 2 Mo a provoqué la réception des en-têtes suivants :
Allow : OPTIONS, GET, HEAD, POST
Content-Length : 0
Allow : OPTIONS, GET, HEAD, POST
Content-Length : 5660
Content-Type : text/html
GET /maRessource HTTP/1.1
HTTP/1.1 200 OK
Date: Tue, 11 Feb 2014 16:08:38 GMT
Server: Apache/2
Last-Modified: Wed, 01 Sep 2004 13:24:52 GMT
Etag: "40d7-3e3073913b100"
Accept-Ranges: bytes
Content-Length: 16599
Cache-Control: max-age=21600
Expires: Tue, 11 Feb 2014 22:08:38 GMT
p3p: policyref="http://www.w3.org/2001/05/P3P/p3p.xml"
Content-Type: text/html; charset=iso-8859-1
GET /monDocument.pdf HTTP/1.1
Status Code: 200 OK
Accept-Ranges: bytes
Access-Control-Allow-Origin: *
Cache-Control: max-age=21600
Content-Length: 2002597
Content-Type: application/pdf; qs=0.001
Date: Tue, 11 Feb 2014 21:01:28 GMT
Etag: "1e8ea5-4931293d8dc80"
Expires: Wed, 12 Feb 2014 03:01:28 GMT
Last-Modified: Wed, 20 Oct 2010 20:51:46 GMT
Server: Apache/2
11. Zaghir Y Rest Page 11 sur 17
En ré exécutant la requête GET et en y ajoutant le header (en-tête) Range, le serveur distant
retourne des informations partielles. De ce fait, le code HTTP n’est plus 200 (OK) mais 206 (Partial
Content).
L’attribut Range peut prendre les valeurs :
bytes 0-n : les n+1 premiers octets.
bytes n1-n2 : les octets d’index n1 à l’index n2.
bytes -n : les n derniers octets.
bytes n- : de l’octet d’index n+1 à la fin.
bytes n1-n2,n3-n4 : deux ensembles contenant les données de l’octet d’index n1 à l’index n2,
puis de l’index n3 à l’index n4.
Dans le cas suivant, la nouvelle requête, avec Range, demande les 101 premiers octets du
document PDF.
Par extrapolation, en ajoutant de nouvelles unités de mesure, il serait théoriquement possible de
coder la pagination d’éléments non pas à l’aide de paramètres d’URL mais directement dans les en-
têtes HTTP, si la RFC le permettait. Exemples : page, utilisateur.
b. Conditional GET
Lorsqu’une page, ou une ressource, a déjà été lue et mise en cache côté client, il peut être utile d’en
récupérer une version mise à jour uniquement dans le cas d’une modification.
Plutôt que de faire une requête HEAD puis éventuellement une requête GET, la RFC 2616 indique la
possibilité de faire un GET conditionnel.
Pour ce faire, il faut, au choix, ajouter l’un des en-têtes suivants à la requête.
bytes 0-499
bytes 500-1000
bytes -500
bytes -500
bytes 500-1000,1001-1501
bytes 500-1000,800-1501
GET /monDocument.pdf HTTP/1.1
Range: bytes=0-100
Status Code: 206 Partial Content
Accept-Ranges: bytes
Access-Control-Allow-Origin: *
Cache-Control: max-age=21600
Content-Length: 101
Content-Range: bytes 0-100/2002597
Content-Type: application/pdf; qs=0.001
Date: Tue, 11 Feb 2014 21:11:49 GMT
Etag: "1e8ea5-4931293d8dc80"
Expires: Wed, 12 Feb 2014 03:11:49 GMT
Last-Modified: Wed, 20 Oct 2010 20:51:46 GMT
Server: Apache/2
12. Zaghir Y Rest Page 12 sur 17
If-Modified-Since
If-Unmodified-Since
If-Match
If-None-Match
If-Range
Voir le chapitre sur les en-têtes HTTP pour les détails de ces en-têtes.
Lors de requêtes GET conditionnelles, le serveur renvoie une réponse 200 (OK) complète ou un code
304 (Not Modified) selon les cas.
3. POST
La méthode POST est communément utilisée pour transmettre les informations d’un formulaire, par
exemple, pour poster un commentaire sur un article, ou un message dans un forum.
Lorsque le traitement par le serveur des données transmises est terminé, il doit adapter sa réponse
(code retour et en-têtes). Une requête POST ne peut pas être mise en cache.
a. Nouvelle ressource sans URL
Si une nouvelle ressource a été créée, mais qu’elle n’a pas d’URL d’accès qui lui est propre, le code
retour est 200 (OK).
b. Nouvelle ressource avec une URL
Si une nouvelle ressource a été créée, et qu’elle a une URL d’accès qui lui est propre, le code retour
devrait être 201 (Created). L’en-tête Location est ajouté avec comme valeur le chemin absolu vers la
nouvelle ressource, afin de rediriger vers ladite ressource.
c. Pas de nouvelle ressource
Si les données transmises en POST ne correspondent pas à la création d’une nouvelle ressource, le
code retour est 204 (No Content).
4. PUT et PATCH
Les méthodes PUT et PATCH peuvent toutes deux être utilisées pour modifier une ressource,
transmise dans son intégralité avec la méthode PUT, et dont seuls les champs modifiés sont transmis
dans le cas d’une requête PATCH.
a. PUT
POST /ajouterUnArticle HTTP/1.1
{
"titre" : "mon titre",
"contenu" : "mon contenu"
}
Status Code : 201 Created
Location : http://www.monsite.com/article/article123
13. Zaghir Y Rest Page 13 sur 17
La méthode PUT, comme la méthode POST, peut être utilisée pour créer une ressource. Le serveur
répondra avec les mêmes codes retour, 200 (OK), 201 (Created), 204 (No Content) mais n’indiquera
pas d’en-tête Location.
Comme la requête POST, une requête PUT ne peut pas être mise en cache.
Cependant, au contraire de la méthode POST, avec une méthode PUT, si l’URL de la ressource a été
modifiée, le serveur devra répondre un code retour 301 (Moved permanently).
La méthode PUT peut aussi être utilisée pour modifier une ressource, qu’elle doit dans ce cas
transmettre dans son intégralité au serveur.
Si le serveur reçoit, parmi les en-têtes de la requête, un en-tête qu’il n’est pas en mesure
d’interpréter, il doit retourner un code retour 501 (Not Implemented).
Dans un wiki, la modification d’un article provoque la mise en archive de l’ancienne version et la
modification de la version courante. Dans ce cas, la réponse à la requête PUT contiendra l’ensemble
des URI créées.
b. PATCH
La méthode PATCH est semblable à la méthode PUT, mais n’impose pas de retransmettre la
ressource dans son intégralité. Seules les données modifiées sont transmises.
Si la requête transmise en méthode PATCH contenait un en-tête Content-Version, la réponse
contiendra, quant à elle, un en-tête Derived-From.
5. LINK et UNLINK
Les méthodes LINK et UNLINK permettent d’indiquer les relations entre différentes ressources. Elles
provoquent une invalidation du cache éventuel des ressources.
La méthode LINK permet d’ajouter une relation.
PUT /modifierUnArticle HTTP/1.1
{
"titre" : "mon titre modifié",
"contenu" : "mon contenu",
identifiant : /article/123
}
Status Code : 200 OK
PATCH /modifierUnArticle HTTP/1.1
{
"titre" : "mon titre modifié",
"identifiant" : 123
}
Status Code : 200 OK
LINK /lienArticleCategorie HTTP/1.1
{
"article" : "/article/123",
"categorie" : "/categorie/1"
}
14. Zaghir Y Rest Page 14 sur 17
La méthode UNLINK, quant à elle, supprime une relation.
6. DELETE
La méthode DELETE est utilisée pour supprimer une ressource.
Trois codes retour peuvent être renvoyés par le serveur.
200 (OK) : si la demande a bien été prise en compte (cela ne garantit cependant pas la
suppression réelle de la donnée, il faut alors regarder dans la réponse l’état de la demande).
202 (Accepted) : si la demande a bien été prise en compte, mais que sa réalisation n’a pas
encore débuté (la ressource est par exemple marquée pour suppression).
204 (No Content) : la demande a bien été enregistrée et le contenu n’existe plus ; il ne peut
être retourné dans la réponse.
Si vous désirez pouvoir gérer des rollbacks (annulation de la suppression), il est judicieux de
retourner un code 200 (OK) et de mettre dans le corps de la réponse la ressource à supprimer. Dans
ce cas, le client pourra réutiliser la ressource pour, par exemple, la recréer à l’identique.
Rest définition
REST (Representational State Transfer) ou RESTful est un style d’architecture permettant de
construire des applications (Web, Intranet, Web Service). Il s’agit d’un ensemble de conventions et
de bonnes pratiques à respecter et non d’une technologie à part entière. 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) mais utilise d’autre protocole(FTP..SMPT) pour envoyer et
recevoir les données (Bon pratique).
REST a été créé en 2000 par Roy T. Fieldling, également créateur du projet Apache HTTP Server et
membre de la fondation Apache.
Il s’agit d’une architecture permettant à un client d’échanger avec un serveur de manière unitaire,
très structurée et gérant le cache. Ainsi, il est possible de mettre en place des couches qui évoluent
de manières autonomes.
Classiquement, dans le cas d’un contexte web (WWW - World Wide Web), tel qu’abordé dans ce
livre, il s’agit d’une interface web pour le client, et d’une application de gestion de données pour le
serveur, qui communiquent ensemble.
REST est indépendant du format représentant les données, que ce soit JSON, XML, ou une autre
forme de sérialisation.
Une programmation statless ou statful
REST est-elle une architecture stateless (sans état) ou stateful (avec état) ?
La réponse est « stateless ». Il n’y a pas de notion de session (au sens large du terme) : le serveur ne
se souvient pas des enchaînements des requêtes, ne fait pas varier les réponses selon un
enchaînement particulier et ne stocke pas d’informations autres que les actions demandées sur les
ressources (création, modification, suppression...).
Vous trouverez au fil de vos lectures des mentions à des applications exposant leurs services en REST,
et à d’autres applications exposant leurs services de manière RESTful.
Si une application est sans état, utilise uniquement des méthodes HTTP, expose sa structure dans
les URI et qu’elle utilise dans ses requêtes du XML et/ou du JSON, elle respecte les différents
préceptes de REST ; elle est donc RESTful.
En résumé, une application qui ne s’expose qu’en REST est RESTful. Si elle s’expose autrement, alors
elle n’est pas RESTful.
15. Zaghir Y Rest Page 15 sur 17
Liens vers les ressources
REST est une architecture centrée sur des ressources de l’application. Ces ressources sont lues et/ou
modifiées à l’aide de verbes, qui sont les méthodes du protocole HTTP.
De manière générale, on peut dégager la structure de liens suivante.
Dans les exemples qui vont suivre, les liens seront composés uniquement de la partie gérée en REST
(pas de nom de domaine, etc.).
Les appels pourront éventuellement être accompagnés de paramètres d’URL, ou d’en-têtes, pour
filtrer les résultats.
1. Action sur l’ensemble des ressources d’un type
De manière usuelle, pour exécuter une action sur l’ensemble des ressources d’un type T, il faut
appeler une URL de forme /T.
Un appel en méthode GET sur le lien /TitreMusique est un appel pour lire l’ensemble des objets de
type TitreMusique disponibles.
2. Action sur une ressource donnée
Pour exécuter une action sur une ressource donnée d’un type T, il faut appeler une URL de forme /T
en ajoutant ensuite une ou plusieurs variables discriminantes V pour obtenir une URL de forme /T/V.
Un appel en méthode GET sur le lien /TitreMusique/1 retourne le titre d’identifiant 1.
3. Action sur une ressource liée
GET /TitreMusique
GET /TitreMusique/1
VERBE URI VERSION HTTP
HEADERS /En têtes
Date :Tue, 19 Jan 2016 18 :15 :41 GMT
Accept-language : en-us,en ;q=0.8
Cookie : 123456789….
Referer : http://www.youssefz.com/
Corps
Les informations à envoyer
name=jean
titre=titreici& ;message=monmessageici
Verbe Http Fichier Version de HTTP
Entête HTTP
16. Zaghir Y Rest Page 16 sur 17
Pour exécuter une action sur une ressource A d’un type TA liée à une ressource B d’un type TB, qui
possède une variable discriminante VB, il faut appeler une URL de forme /TB/VB/TA.
Un appel en méthode GET de /Album/1/TitreMusique retourne l’ensemble des titres relatifs à
l’album d’identifiant numéro 1.
Il est aussi envisageable d’exécuter un autre type d’action, dont le verbe ne serait pas présent dans le
protocole HTTP. Dans l’exemple qui suit, on veut utiliser le verbe acheter.
Ce type d’URL est particulièrement adapté si les ressources ont été liées à l’aide de la méthode LINK.
Sinon, il est tout à fait approprié de plutôt passer un paramètre.
4. Format de retour
Selon le type de retour désiré par le client, deux méthodes sont communément envisageables.
Mettre une extension en fin d’URL permet d’avoir l’illusion d’un fichier réel. Par exemple, dans le cas
présent un PDF (Portable Document Format) deviendrait directement enregistrable sur le poste du
client.
Mettre le type de retour désiré dans les en-têtes est une procédure conforme au protocole HTTP.
pour donner l’accès à différentes ressources :
URL Description
/api Point d’entrée.
/api/:collection Accède à une collection.
/api/:ressource/:collection/:id Accède à une ressource unique.
/api/:collection/:id/sous_collection Accède à une sous-collection.
GET /Album/1/TitreMusique
POST /TitreMusique/1/acheter
GET /TitreMusique/?album=1
GET /Facture/1.pdf
GET /TitreMusique/1
Accept : application/json
17. Zaghir Y Rest Page 17 sur 17
Le tableau ci-dessous décrit quelques codes de retour HTTP utiles :
/api/:collection/:id/sous_collection/:sous_id Accède à une sous-ressource unique.
Code
HTTP
Description
200 La requête a été exécutée avec succès et retourne un contenu normal.
201 La requête a été exécutée avec succès et une nouvelle ressource a été créée.
204 La requête a été exécutée avec succès et ne retourne aucun contenu.
400 Le corps de la requête n’a pas pu être interprété.
401 L’accès à la ressource n’est pas autorisé : une authentification est
nécessaire pour accéder à la ressource demandée ou l’utilisateur n’a pas le
droit d’accéder à la ressource.
404 La ressource demandée n’existe pas.
422 Les champs du corps de la requête sont invalides.
500 Une erreur s’est produite sur le serveur.