RESTFul

CORINNE AMEL ZAYANI

 Table des
matières

Table des matières

A. Principe.................................................................................................................................7
B. LE PROTOCOLE HTTP.......................................................................................................7
1. Définition...........................................................................................................................7
2. Méthodes du protocole HTTP...........................................................................................8
C. Les Règles de RESTful.........................................................................................................8
1. Règle n°1 :.........................................................................................................................9
2. Règle n°2 :.........................................................................................................................9
3. Règle n°3 :.......................................................................................................................10
4. Règle n°4 :.......................................................................................................................10
5. Règle n°5 :.......................................................................................................................11
A. JAX-RS : Spécification.......................................................................................................13
B. JAX-RS: fonctionnement....................................................................................................14
C. Annotations.........................................................................................................................15
D. Exemple...............................................................................................................................16

3
 Problèmes de SOAP

4
Problèmes de
I-

I
SOAP

Les inconvéniants
 SOAP utilise seulement XML
- pour échanger des messages
- pour consommer le SW, il faut le WSDL qui est un document XML
 Au niveau du transport du message XML, il prend de l'espace (le fait que
XML est verbaux) et
 Au niveau de son chargement en mémoire, il demande de ressource
(mémoire lors du parsage du message côté client)

5
 Problèmes de SOAP

Ex em ple : Explication du XML est verbaux

Sur l'exemple ci-dessous, on remarque que le message le plus intéressant c'est le
résultat : 58
Mais pour avoir ce simple résultat, il faut l'envelopper par des balises. Ceci
représente un inconvénient majeur qui est dû au XML est verbaux

 le second inconvénient majeur, il faut parser ce message côté client pour le

charger dans la mémoire, ce qui prend beaucoup de temps

Le protocole SOAP a ignoré plusieurs choses dans le header de HTTP, il s'est limité
à utiliser seulement le corps de la requête pour envoyer l'information sous forme de
message XML. La requête SOAP est une requête HTTP dont le corps contient un
message XML. Ce dernier est constitué du nom de l'opération a exécuté et les
paramètres de l'opération.
L'idée principale pour répondre à ces inconvénients : comment utiliser une
simple requête http pour consommer un WS ?

6
REST
II -

II
(REpresentational
State Transfer)
ou RESTful

A. Principe

REST
 n'est pas un protocole, mais c'est un norme proposé par Roy Fielding en
2000 dans une thèse de doctorat.
 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).
 est un style d'architecture pour les systèmes hypermédia distribués,
 permet de construire des applications (Web, Intranet, Web Service).

REST VS SOAP
 Il s'agit d'un ensemble de conventions et de bonnes pratiques à respecter et
non d'une technologie à part entière comme le cas du XML.
SOAP n'est pas obligatoirement un Http ( SOAP c'est un message XML
transporter par un protocole HTTP ou autre protocole) et RESTful c'est du
HTTP, pour cela c'est une norme qui respecte 5 règles

B. LE PROTOCOLE HTTP

1. Définition

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

7
 REST (REpresentational State Transfer) ou RESTful

 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

2. Méthodes du protocole HTTP

Une requête HTTP peut être envoyée en utilisant les méthodes suivantes:
 GET : Pour récupérer le contenu d'un document
 POST : Pour soumissionner des formulaires (Envoyer, dans la requête, des
données saisies par l'utilisateur )
 PUT pour envoyer un fichier du client vers le serveur
 DELETE permet de demander au serveur de supprimer un document.
 HEAD permet de récupérer les informations sur un document (Type,
Capacité, Date de dernière modification etc...)

Requête HTTP
De quoi est constitué la réponse HTTP?
1. header
- la date
- le serveur
- la version
- la date de la dernière modification
2. coprs de la réponse : le résultat retouné

Remarque
Le protocole SOAP ignore ce qui est fournit par HTTP tel que le header. SOPA
repose seuelemnt sur le corps de la requête pour faire passer le message XML.
En plus ce message XML peut être transporté par autre protocole tel que FTP

C. Les Règles de RESTful

Règle n°1 :
 l'URI (Uniforme ressource Identifier) comme identifiant des ressources
Règle n°2 :
 les verbes HTTP comme identifiant des opérations
Règle n°3 :
 les réponses HTTP comme représentation des ressources
Ces trois règles sont des normes à respecter
Règle n°4 :

8
 REST (REpresentational State Transfer) ou RESTful

 les liens comme relation entre ressources

Règle n°5 :
 un paramètre comme jeton d'authentification
Ces deux dernières règles dépendes de l'application
RESTFul, càd on respecte les trois premières règles REST, c.à.d 3/4 ou 5 règles

1. Règle n°1 :

REST se base sur les URI (Uniform Resource Identifier) afin d'identifier une
ressource.
Une application se doit de construire ses URI (et donc ses URL) de manière précise,
en tenant compte des contraintes REST.
Il est nécessaire de prendre en compte la hiérarchie des ressources et la
sémantique des URL pour les éditer.

Exemple : Quelques exemples de règle 1 pour une application qui

gère des livres (books)
on utilise /books c'est au pluriels book
Liste des livres
 NOK : http://mywebsite.com/book
 OK : http://mywebsite.com/books
Affichage d'un livre selon un identifiant
 NOK : http://mywebsite.com/book/display/87
 OK : http://mywebsite.com/books/87
=> On appel " /books/87 "
Path parameter
Tous les commentaires sur un livre
 NOK : http://mywebsite.com/books/comments/87
 OK : http://mywebsite.com/books/87/comments
Filtre et tri sur les livres
 NOK : http://mywebsite.com/books/filtre/policier/tri/asc
 OK : http://mywebsite.com/books?fitlre=inormatique&tri=asc
 => On appel " books?fitlre=inormatique&tri=asc"
Request parameter c.à.d un paramètre (ou plusieurs paramètres) qui
vient après ?
Cette requête est semblable à ce qu'on demande à la partie Backend (en
utilisant une DB relationnelle) select * from books where filter =
informatique and tri=asc

2. Règle n°2 :

Les verbes HTTP comme identifiant des opérations

Utiliser les verbes HTTP existants plutôt que d'inclure l'opération dans l'URI de la
ressource.
 GET pour consulter/ afficher (READ)
 POST pour ajouter (CREATE)
 PUT mettre à jour tous les attributs
 PATCH mettre à jour que les attributs envoyés via la requête (update

9
 REST (REpresentational State Transfer) ou RESTful

partiel)
 DELETE pour supprimer

Ex em ple : Compléter la règle 1 par règle 2

Créer un livre
 NOK : GET http://mywebsite.com/books/create
 OK : POST http://mywebsite.com/books
Afficher
 NOK : GET http://mywebsite.com/books/display/87
 OK : GET http://mywebsite.com/books/87
Mettre à jour
 NOK : POST http://mywebsite.com/books/editer/87
 OK : PUT http://mywebsite.com/books/87
Supprimer
 NOK : GET http://mywebsite.com/books/87/delete
 OK : DELETE http://mywebsite.com/books/87

3. Règle n°3 :

Les réponses HTTP comme représentation des ressources

 Contrairement au réponse SOAP qui exige XML
 avec la norme RESTFul la réponse HTTP envoyé au client en fonction de la
demande du client
 une ressource peut avoir plusieurs représentations dans des formats divers :
HTML, XML, CSV, JSON, etc.
 C'est au client de définir quel format de réponse souhaitée recevoir qui est
présenté dans l'entête (Header) qui est renommé depuis la version
HTTP 1.O par Accept

Remarque
Depuis la version HTTP 1.0, le Header s'appel Accept qui permet au client de
spécifier le type MIME qu'il accepte (exp. JPEG, txt, XML, etc.) c.à.d de spécifier la
forme de la ressource que le client attend

Ex em ple : demander une réponse en HTML ou en json

 GET /books
Host: mywebsite.com
Accept: text/html
 GET /books
Host: mywebsite.com
Accept: application/json

4. Règle n°4 :

Les liens comme relation entre ressources

Cette règle 4 permet d'introduire des liens entre les ressources en respectant un
norme
càd si on a la ressource livre, on introduit une relation avec les ressources

10
 REST (REpresentational State Transfer) ou RESTful

auteur(s), l'éditeur

Exemple : Exemple de réponse en XML d'une liste paginée de

livres :

1 <?xml>
2 <search>
3 <link rel="self" title="self" href="http://mywebsite.com/books?
q=policier&page=1&c=5" />
4 <link rel="next" title="next" href="http://mywebsite.com/books?
q=policier&page=2&c=5" />
5 <link rel="last" title="last" href="http://mywebsite.com/books?
q=policier&page=4&c=5" />
6 <book>
7 //...
8 </book>
9
10 </search>

le sens de lien par exemple <link rel="next" permet de faire suivant

la ressource définie dans href qui est par exemple "http://mywebsite.com/books?
q=policier&page=1&c=5"
cette règle 4 permet d'introduire le lien entre les ressource est un next

Complément
 Ainsi l'IANA donne une liste de relation parmi lesquelles :
- contents
- edit
- next
- last
- payment
- etc.
 La liste complète sur le site de l'IANA :
http://www.iana.org/assignments/link-relations/link-relations.xml

5. Règle n°5 :

sécurisé les applications basée RESTful

C'est un des sujets les plus souvent abordé quand on parle de REST : comment
authentifier une requête ?
La réponse est très simple et est massivement utilisée par des APIs renommées
(Google, Yahoo, etc.) : le jeton d'authentification.
Chaque requête est envoyée avec un jeton (token) passé en paramètre $_GET de
la requête.
Ce jeton temporaire est obtenu en envoyant une première requête
d'authentification puis en le combinant avec nos requêtes.
Ainsi, on peut construire le scénario suivant :

Exemple : Paramètre comme jeton d'authentification

Envoyer un jeton d'authentification différent pour chaque requête

StateFul vs Stateless
StateFul (avec état): sécurisé les sessions et les coockies (càd la session est géré
par le serveur qui envoie le numéro de la session qui sera enregisté dans une
cookie. A chaque fois qu'on envoi une requête, on envoi une session ID, une fois

11
 REST (REpresentational State Transfer) ou RESTful

qu'on envoi l'ID, le serveur peut identifié la session

=> a des inconvénient pour RESTFul
Stateless plus pratique : dans ce cas ce n'est pas le serveur qui gère les sessions
mais c'est le client qui gère sa session
quand l'user saisit son login et MdP
le client envoie sa requête avec son login et MdP, le serveur authentifie l'utilisateur
et il lui envoie un token (jeton)
Il y a plusieurs sorte de token, le plus utilisé JWT (Json Web Token)
Ce token correspond à la session de l'utilisateur à chaque accès à l'application
Ce token est constitué de plusieurs informations, tels que user name, date
d'expiration du token, etc
L'application quand elle reçoit se token, identifie le client

12
Mise en œuvre de
III -

III
REST

A. JAX-RS : Spécification

Rappel : JAX-WS
Pour mettre en œuvre un SW basé SOAP, on utilise une spécification JAX-WS

Pour REST, on utilise une autre spécification nommée JAX-RS

JAX-RS : Spécification
est une API comme JAX-WS créée dans JEE
JAX-RS permet de gérer des SW de type REST
Tout API demande une implémentation
Différentes implémentations de la spécification JAX-RS sont disponibles
 JERSEY : implémentation de référence fournie par Oracle Site projet :
http://jersey.java.net
 CXF : fournie par Apache, la fusion entre XFire et Celtix Site projet :
cxf.apache.org
 RESTEasy : fournie par JBoss Site projet : www.jboss.org/resteasy
 RESTlet : un des premiers framework implémentant REST pour Java : Site
projet : www.restlet.org

13
 Mise en œuvre de REST

Le développement de SW REST repose sur l'utilisation de classes et d'annotations

B. JAX-RS: fonctionnement

Comme a été mentionné dans le chapitre SW SOAP, le Web service est crée par un
langage de programmation tel que JAVA.
Ce service doit être déployé dans un serveur web qui est représenté par un
webContainer qui repose sur un middelware tel que jersey
Avec JEE, on utilise aussi une spécification tel que le JAX-RS qui est implémenté par
Jersey pour gérer SW-REST

Pour qu'un client invoque une méthode de SW, il envoie seulement une requête
HTTP avec l'une de méthodes GET, POST, etc.
Le container reçoit cette requête. Puis le container la passe à un middelware Jersey
qui implémente JAX-RS, dans le cas de JEE c'est une servlet. Cette requête appel la
méthode, Ensuite il récupère le résultat le middelware. Enfin ce dernier envoie le
résultat au client au format qui dépend de la demande de client (HTML, XML, json)

14
 Mise en œuvre de REST

(règle 3)

Dans la spécification de JAX-RS, il y a l'équivalent du WSDL qui contient la

description de l'interface du WS c'est le WADL (Web Application Description
language) c'est le langage de description des applications Web, qui est un
document XMLqui permet de faire la description de l'interface d'un WS Rest
Dans WADL, on trouve
 Quelles sont les différentes requêtes qu'on peut envoyer ?
 pour chaque requête, quelle méthode qu'on va utiliser (GET, PUT, etc) ?
 Quel est l'URL qu'on va utiliser
 Quels sont les formats à envoyer

C. Annotations

Ressources d'un service REST

Une ressource web dans le contexte des services REST est une simple classe Java
(on parle de POJO pour Plain Java Object ).
Cette classe doit être annotée par @Path, ou, à défaut, au moins une de ses
méthodes doit l'être.
 @Path indique le chemin d'accès à un service
Cette annotation peut se poser sur la classe de service, ou sur une méthode, ou sur
les deux. Elle désigne d'une part l'URI d'accès au service et à ses sous-services, et
d'autre part la présence de paramètres dans cette URI.

Associer une requête à une méthode

Les informations de déploiement sont gérées par l'utilisation des annotations.
JAX-RS fournit une annotation pour toutes les méthodes HTTP avec l'importation
javax.ws.rs.
Cinq annotations sont définies, qui peuvent annoter certaines méthodes d'un
service REST : @GET, @POST, @PUT, @DELETE, et @HEAD.
Elles correspondent aux cinq méthodes HTTP qui portent le même nom. On ne peut
poser chaque annotation qu'une seule fois sur une unique méthode dans une classe
donnée, pour un chemin d'accès donné.
Une telle méthode doit être public. Lorsqu'une telle requête arrive, la bonne
méthode est invoquée, avec les paramètres annotés correctement positionnés.
Enfin, une méthode annotée peut aussi porter un paramètre non annoté, que l'on
appelle le paramètre d'entité. Ce paramètre portera l'intégralité de la requête.

Annotations des paramètres

La spécification REST définit six annotations pour associer les éléments de la
requête à des champs ou des paramètres du service REST invoqué.
Ces annotations peuvent être posées sur des champs, des paramètres de
méthodes, ou des setters .
Ces annotations sont les suivantes.
 @PathParam est l'annotation que nous avons vue dans notre premier
exemple. Elle permet d'associer un morceau de l'URL de requête à un champ
ou un paramètre.
 @QueryParam et @FormParam permettent d'associer un paramètre de la
requête à un champ ou un paramètre d'une méthode de la classe.

15
 Mise en œuvre de REST

 @Consumes / @Produces pour indiquer respectivement le type de

contenu attendu dans la requête et le type de contenu de la réponse.
 @CookieParam pour récupérer la valeur d'un Cookie HTTP, permet
d'associer une valeur stockée dans un cookie ou l'instance de Cookie elle-
même.
 @HeaderParam pour récupérer la valeur d'un en-tête HTTP, permet
d'associer une valeur d'un champ HTTP à un champ ou un paramètre d'une
méthode de la classe.
 @MatrixParam permet d'associer un paramètre HTTP matriciel à un champ
ou un paramètre de méthode de notre classe. Le problème est que les URL
portant des paramètres matriciels ne sont pas clairement supportées par les
navigateurs et les serveurs web. Cette annotation est donc à utiliser avec
précautions.

D. Exemple

Les WS peuvent publier des données et/ou permettre aux clients de modifier les
données métiers, prenant l'exemple d'un service de Bibliothèque

Ex em ple : Objet métier : livre

1 package metier;
2
3 import java.io.Serializable;
4
5 import javax.xml.bind.annotation.XmlRootElement;
6
7 //@XmlRootElement(name = "livres")
8 public class Livre implements Serializable {
9 private int id=0;
10 private String titre;
11 private Date datePubli;
12
13 public Livre() {
14
15 }
16
17 public Livre (int id,String titre) {
18 super();
19 this.id = id;
20 this.titre = titre;
21
22 }
23
24 public int getNumLivre() {
25 return id;
26 }
27 public void setNumLivre(int numLivre) {
28 this.id = numLivre;
29 }
30 public String getTitre() {
31 return titre;
32 }
33 public void setTitre(String titre) {
34 this.titre = titre;
35 }
36
37
38 }

16
 Mise en œuvre de REST

1 package service;
2
3 import java.util.ArrayList;
4 import java.util.Date;
5 import java.util.List;
6
7 //import metier.*;
8
9
10 //Cette classe qui sert à persister toutes les informations
concernant le service Web
11
12 public class LivreDB {
13
14
15 private static List<Livre> livre = new ArrayList<Livre>();
16 //private static int id = 1;
17
18 static {
19 livre.add(new Livre(1, "SW"));//, new Date()));
20 livre.add(new Livre(2, "SOA"));//, new Date()));
21 }
22
23 public static List<Livre> getLivres() {
24 return livre;
25 }
26
27 }

Exemple : Service Bibliothèque

1 package service;
2
3
4 import javax.ws.rs.DELETE;
5 import javax.ws.rs.GET;
6 import javax.ws.rs.POST;
7 import javax.ws.rs.PUT;
8 import javax.ws.rs.Path;
9 import javax.ws.rs.Produces;
10 import javax.ws.rs.QueryParam;
11 import javax.ws.rs.core.MediaType;
12 import javax.ws.rs.core.Response;
13 import javax.ws.rs.core.Response.Status;
14
15 import java.util.Date;
16
17 import metier.Livre;
18
19 import java.util.Iterator;
20 import java.util.List;
21
22 import javax.websocket.server.PathParam;
23
24
25 @Path("/biblio")
26 //@Produces("application/json")
27 //@Produces("application/xml")
28 public class BiblioService {
29
30 public BiblioService () {
31 }
32
33
34 /**
35 * retourner la liste des livres

17
 Mise en œuvre de REST

36 * @return
37 */
38 @Path("/livres")
39
40 @GET // Méthode HTTP utilisée pour déclencher cette méthode
41 @Produces(MediaType.APPLICATION_JSON)
42 public Response getLivres() {
43 System.out.println("getLivres");
44
45 return Response
46 .status(Status.OK)
47 .entity(LivreDB.getLivres())
48 .build();
49 }
50
51 /**
52 *
53 * retourner un livre en fonction de son identifiant fonctionnel
54 */
55
56
57 @GET // Méthode HTTP utilisée pour déclencher cette méthode
58 //@Path("numLivre-{id}") // Chemin suivant ce template numLivre-1
où 1 est une chaine variable
59 @Path("/livres/{id}")
60 @Produces(MediaType.APPLICATION_JSON)
61
62
63 //Exemple http://localhost:8080/ExempleCoursRest2021/livres/2
64
65 public Response getLivre(@PathParam(value="id") int id) {
66 System.out.println("getLivre" + id);
67
68 for (Livre current : LivreDB.getLivres()) {
69 System.out.println(current.getNumLivre());
70 if (id==current.getNumLivre()) {
71 System.out.println(current.getNumLivre());
72 return Response
73 .status(Status.OK)
74 .entity(current)
75 .build();
76 }
77 }
78 return Response
79 .status(Status.NO_CONTENT)
80 .build();
81 }
82
83 /**
84 * une recherche de Livres par critères passés en paramètre de
la requête (titre).
85 * le sous-chemin associé est /search. Noter que le format de
retour des services est du Json.
86 */
87
88 @GET // Méthode HTTP utilisée pour déclencher cette méthode
89 @Path("/livres/search") // Chemin suivant livres/ pour invoquer
cette méthode
90 @Produces(MediaType.APPLICATION_JSON)
91
92
93 // EXEMPLE
http://localhost:13877/ExempleCoursRest2021/biblio/livres/search?
titre=SW
94
95 public Response searchLivresByCriteria(@QueryParam("titre")
String titre) {
96 System.out.println("searchLibresByCriteria");
97

18
 Mise en œuvre de REST

98 for (Livre current : LivreDB.getLivres()) {

99
100 if (titre.equals(current.getTitre())) {
101 System.out.println(current.getTitre());
102 return Response
103 .status(Status.OK)
104 .entity(current)
105 .build();
106 }
107 }
108 return Response
109 .status(Status.NO_CONTENT)
110 .build();
111 }
112
113 @POST // Méthode HTTP utilisée pour déclencher cette méthode

114 @Path("/livres")
115 @Produces(MediaType.APPLICATION_JSON)
116 public Livre save(Livre livre) {
117 LivreDB.getLivres().add(livre);
118 return livre;
119 }
120
121
122 @PUT // Méthode HTTP utilisée pour déclencher cette méthode

123 @Path("/livres/{code}")
124 @Produces(MediaType.APPLICATION_JSON)
125 public Livre update(Livre livre, @PathParam(value="code") int id)
{
126 LivreDB.getLivres().add(livre);
127 return livre;
128 }
129
130 @DELETE // Méthode HTTP utilisée pour déclencher cette méthode

131 @Path("/livres/{code}")
132 @Produces(MediaType.APPLICATION_JSON)
133 public boolean delete(@PathParam(value="code") int id) {
134 LivreDB.getLivres().remove(id);
135 return true;
136 }
137
138
139 }
140

19
 Mise en œuvre de REST

application.wadl

20
IV - JSON IV

Remarque
 SOAP c'est du XML
 REST c'est en fonction de la demande du client d'après la règle 3 qui peut
être XML, JSON
Le format demandé pour REST c'est le JSON car il est plus pratique

Définition
JavaScript Object Notation – Notation Objet issue de JavaScript) est un format
léger d'échange de données.
 Il est facile à lire ou à écrire pour des humains. Il est aisément analysable
ou générable par des machines.
 est un format texte complètement indépendant de tout langage, mais les
conventions qu'il utilise seront familières à tout programmeur habitué aux
langages descendant du C, comme par exemple : C, C++, C#, Java,
JavaScript, Perl, Python et bien d'autres.
 Ces propriétés font de JSON un langage d'échange de données idéal.

Structures de JSON
JSON se base sur deux structures :
 Une collection de couples nom/valeur.
 Divers langages la réifient par un objet, un enregistrement, une structure,
un dictionnaire, une table de hachage, une liste typée ou un tableau
associatif.
Ces structures de données sont universelles. Pratiquement tous les langages de
programmation modernes les proposent sous une forme ou une autre.
En JSON, les structures de données prennent les formes suivantes :
 Un objet, qui est un ensemble de couples nom/valeur non ordonnés. Un
objet commence par { (accolade gauche) et se termine par } (accolade
droite). Chaque nom est suivi de : (deuxpoints) et les couples nom/valeur
sont séparés par , (virgule).

 Un tableau est une collection de valeurs ordonnées. Un tableau commence

21
 JSON

par [ (crochet gauche) et se termine par ] (crochet droit). Les valeurs sont
séparées par , (virgule).

 Une valeur peut être soit une chaîne de caractères entre guillemets, soit un
nombre, soit true ou false ou null, soit un objet soit un tableau. Ces
structures peuvent être imbriquées.

 Une chaîne de caractères est une suite de zéro ou plus caractères Unicode,
entre guillemets, et utilisant les échappements avec antislash. Un caractère
est représenté par une chaîne d'un seul caractère.

22