Architecture et Services Web RESTful

Emmanuel BRUNO
emmanuel.bruno@univ-tln.fr

Université de Toulon

LIS UMR CNRS 7020

2025-02-25

Informations techniques

Git Repository Status

Category Details
🌿 Current Branch develop
📝 Latest Commit b798c84 (2024-10-03 15:16:24)
🔗 Remote git@github.com:ebpro/notebook-java-restfulws.git
đŸ·ïž Latest Tag No tags

 

☕ Java Development Environment

Component Details
☕ Java Runtime 21.0.6 (openjdk)
🎯 Maven 3.9.9

Les exemples suivants sont accessibles dans le dépÎt :

  • Source: ebpro/sample-jaxrs
  • Branch: develop
  • Latest Commit: dbac38c (fix maven wrapper exec bit, 2025-02-24)
  • Cloned to: ${SRC_DIR}=/home/jovyan/work/materials/github/ebpro/sample-jaxrs

To get it:

git clone -b develop https://github.com/ebpro/sample-jaxrs

Objectifs

Ce document présente les service Web REST en général et par la pratique en Java.

Il s’appuie sur un exemple simple d’application : https://github.com/ebpro/sample-jaxrs qui servira Ă  illustrer les notions et sera Ă©tudiĂ©e en dĂ©tail dans la partie pratique.

L’Approche REST (REpresentational State Transfer)

  • Qu’est-ce que REST ?
    • REpresentational State Transfer
    • Un style architectural pour la conception de services web
    • Offre un accĂšs distant Ă  des ressources via HTTP
  • Principes de REST
    • Interface uniforme en HTTP
    • Stateless : Chaque requĂȘte est indĂ©pendante
    • Cacheable : PossibilitĂ© de mettre en cache les rĂ©ponses
    • Client-Server : SĂ©paration claire des responsabilitĂ©s

RESTful

  • Une approche conformant Ă  ces principes
  • FlexibilitĂ© dans la conception des API
  • Pas une norme, mais une recommandation d’architecture

Important

RESTfull est une approche d’API client/serveur suivant la logique de navigation dans un hypermedia. On parle d’HATEOS (Hypermedia As The Engine Of Application State).

Protocole de communication

Pour définir un protocole de communication, il faut généralement définir :

  • un systĂšme d’identification (d’adressage) des ressources manipulĂ©es,
  • un protocole de communication,
  • un format d’échange de donnĂ©es Ă©ventuellement typĂ©es,
  • un systĂšme de gestion des erreurs.

La logique RESTfull est d’utiliser tout ce que propose HTTP pour Ă©crire une API en HTTP.

L’adressage des ressources

Important

Les ressources (ou ensembles de ressources) de l’application sont identifiĂ©es par des URI. Les URL sont une sorte particuliĂšre d’URI qui indique un moyen d’accĂšs en plus de les identifier de façon unique.

Il n’y a pas de standard pour les API REST. Il vaut gĂ©nĂ©ralement mieux rester simple et cohĂ©rent. Quelques pratiques sont utilisĂ©es classiquement :

  • On utilise des noms (pas des verbes) au pluriel pour les ressources :

    # Toutes les personnes
http://MyServer/MyApp/Persons

  • Utilisation du chemin pour inclure “paramĂštres”

    # La personne d'identifiant 1
http://MyServer/MyApp/Persons/1

L’adressage des ressources (“Jointures”)

  • Eviter les “jointures”.
    • Les chiens de la personne 1
      • http://MyServer/MyApp/Persons/1/Dogs
      • http://MyServer/MyApp/Dogs?master_id=1

L’adressage des ressources (Pagination et tri)

  • Pagination
    • La deuxiĂšme page de personnes en utilisant des pages de 10 personnes.
      • http://MyServer/MyApp/Persons?page=2&page_size=10
      • http://MyServer/MyApp/Persons;page=2;page_size=10 (avec des Matrix Params)
    • filtre qui trie par ordre decroissant de date de crĂ©ation, puis par titre
      • http://MyServer/MyApp/Persons?page=&page_size=10&sort=name,firstname,-created,title
  • Projection
    • La personne d’identifiant 1 restreinte uniquement Ă  certains champs
      • http://MyServer/MyApp/Persons/1?fields=email,firstname,lastname
  • Version : prĂ©fixes /api/v1, /api/v2, 


Le protocole d’échange

Verbe HTTP Utilisation Contraintes
GET AccĂšs Ă  une ressource identifiĂ©e dans l’URL (il peut s’agir d’une collection). Safe, Idempotent
HEAD comme GET mais sans le corps de la requĂȘte (seul le header http est retournĂ©). Utile pour savoir si une ressource a changĂ©. Safe, Idempotent
POST crĂ©ation d’une ressource sans donner l’identifiant.
PUT mise Ă  jour complĂšte d’une ressource identifiĂ©e (voire crĂ©ation en donnant l’identifiant). Idempotent
DELETE suppression d’une ressource. Idempotent
OPTIONS liste les actions possibles sur une ressource. Safe, Idempotent
PATCH RFC 5789, mises à jour partielle d’une ressource.

Endpoints

Un endpoint REST est défini par un verbe HTTP et une URL.

  • Obtenir toutes les personnes :
    • GET http://MyServer/MyApp/Persons
  • Obtenir une personne prĂ©cise par identifiant :
    • GET http://MyServer/MyApp/Persons/1
  • Obtenir toutes les personnes entre 7 et 16ans (avec un filtre) :
    • GET http://MyServer/MyApp/Persons?ageMin=7&ageMax=16
  • Supprimer toutes personnes
    • DELETE http://MyServer/MyApp/Persons
  • Supprimer une personne
    • DELETE http://MyServer/MyApp/Persons/1

La représentation des ressources

Important

Les resources sont gĂ©nĂ©ralement reprĂ©sentĂ©es et Ă©changĂ©es Ă  l’aide de langages autodescriptifs comme XML ou JSON.

Par exemple, une personne peut ĂȘtre prĂ©sentĂ©e :

<?xml version='1.0'?>
<person id='1'>
    <lastname>Doe</lastname>
    <firstname>John</firstname>
</person>
{
  "person": {
    "-id": 1,
    "lastname": "Doe",
    "firstname": "John"
  }
}
  • Les types de donnĂ©es envoyĂ©es ou attendues sont spĂ©cifiĂ©s dans l’entĂȘte de la requĂȘte HTTP par les champs Content-Type: et Accept:
  • Cette spĂ©cification utilise les Internet Media Types (ex. MIME Type - Multipurpose Internet Mail Extensions)
  • Il s’agit d’une liste standard de formats et sous-formats d’échange de donnĂ©es, incluant des exemples tels que text/plain, text/xml, application/json, 


Exemple de graphe

L’exemple ci-dessous sĂ©rialise des objets Java qui reprĂ©sente un auteur et un livre en JSON et en XML. (Le dĂ©tail est expliquĂ© plus loin).

{
  "books" : [ {
    "id" : 1,
    "title" : "Effective Java (English Edition)",
    "authors" : [ 1 ]
  } ],
  "authors" : [ {
    "id" : 1,
    "name" : "Bloch",
    "firstname" : "Joshua",
    "books" : [ 1 ]
  } ]
}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ebjax:library xmlns:ebjax="http://bruno.univ-tln.fr/sample-jaxrs" xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <authors>
        <author id="Author-1">
            <id>1</id>
            <name>Bloch</name>
            <firstname>Joshua</firstname>
            <books>
                <book>Book-1</book>
            </books>
        </author>
    </authors>
    <books>
        <book id="Book-1">
            <id>1</id>
            <title>Effective Java (English Edition)</title>
            <authors>
                <author>Author-1</author>
            </authors>
        </book>
    </books>
</ebjax:library>

Les code de retours

Important

Le code de retour des mĂ©thode est un code HTTP. Il est indiquĂ© de façon standard dans l’entĂȘte de la rĂ©ponse et peut ĂȘtre rĂ©pĂ©tĂ© dans le contenu si une enveloppe est proposĂ©e.

SuccĂšs

Code Signification Usage
200 Ok RequĂȘte traitĂ©e avec succĂšs.
201 Created Nouvelle ressource créée.
204 No Content Pas de contenu, pas exmple lors d’une requĂȘte DELETE rĂ©ussie.
206 Partial Content Seulement une partie de résultat est retourné par exemple en cas de pagination (non explicite).
304 Not Modified Utilisation du cache possible.

Echec

Code Signification Usage
400 Bad Request La requĂȘte est invalide et ne peut pas ĂȘtre traitĂ©e par le serveur.
401 Unauthorized La requĂȘte nĂ©cessite que le client soit authentifiĂ©.
403 Forbidden Le client est authentifiĂ© mais l’utilisateur n’est pas autorisĂ© Ă  accĂ©der Ă  cette ressource.
404 Not Found La ressource demandĂ©e n’existe pas.
500 Internal Server Error C’est une erreur gĂ©nĂ©rique de fonctionnement, elle devrait toujours ĂȘtre accompagnĂ©e d’une description

Un Ă©change REST = un Ă©change HTTP

Important

Un Ă©change d’une API REST correspond donc exactement Ă  un Ă©change http.

  • RequĂȘte HTTP
    • Verbe, URL, version HTTP, en-tĂȘte, corps (Ă©ventuellement vide).
  • RĂ©ponse HTTP
    • Code de retour, mĂ©tadonnĂ©es dans l’en-tĂȘte, corps (Ă©ventuellement encapsulĂ©).

Quelques exemples complets

RequĂȘte de crĂ©ation d’une personne :

POST http://MyServer:8080/MyApp/Persons/
Host: MyServer:8080
Content-Type: application/json; charset=utf-8
Content-Length: 36
{"lastname": "Doe",
 "firstname": "John"}

RequĂȘte de modification d’une personne (id dans l’URL):

PUT http://MyServer:8080/MyApp/Persons/1
Host: MyServer:8080
Content-Type: application/json; charset=utf-8
Content-Length: 12
{"age":"18"}

Utilisation

Une requĂȘte REST peut ĂȘtre envoyĂ©e par programmation ou en utilisant un programme dĂ©diĂ© comme curl en ligne de commande, postman pour chrome ou RestClient pour firefox.

Regardez les options de la commande curl pour rĂ©aliser des requĂȘtes HTTP.

%%shell 
curl -H "Accept: application/json" \
     -H "User-Agent: Demo Script" \
     -X GET "https://nominatim.openstreetmap.org/search?q=Universit%C3%A9+de+Toulon&format=json&limit=1"
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed

  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
100   557  100   557    0     0   3023      0 --:--:-- --:--:-- --:--:--  3010
100   557  100   557    0     0   3023      0 --:--:-- --:--:-- --:--:--  3010
[{"place_id":74901953,"licence":"Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright","osm_type":"way","osm_id":288649901,"lat":"43.13540745","lon":"6.016159230356979","class":"amenity","type":"university","place_rank":30,"importance":0.4365136800558239,"addresstype":"amenity","name":"Université de Toulon","display_name":"Université de Toulon, Impasse Roger Coste, Le Thouar, La Garde, Toulon, Var, Provence-Alpes-CÎte d'Azur, France métropolitaine, 83130, France","boundingbox":["43.1328214","43.1379869","6.0092534","6.0254597"]}]