Client REST avec Jakarta RESTful Web Services

Emmanuel BRUNO

emmanuel.bruno@univ-tln.fr

Université de Toulon

LIS UMR CNRS 7020

2025-02-26

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

Exemples

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

Introduction aux Clients REST

• Un client REST est un composant logiciel qui :
  • Interagit avec des APIs RESTful
  • Envoie des requêtes HTTP
  • Traite les réponses
• En Java, Jakarta RESTful Web Services (JAX-RS) propose :
  • Une API fluide
  • Une approche élégante
  • Un design moderne

Types de Clients REST

Clients Java Standards

• Client HTTP natif
  • Simple, sans dépendances
  • Intégré à Java
  • Bas niveau
• Client Jakarta REST
  • API fluide moderne
  • Support des standards
  • Extensible

Clients Modernes

• Client REST asynchrone
  • Non bloquant
  • Haute performance
  • Réactif
• Client Quarkus
  • Déclaratif
  • Cloud native
  • Microservices

Tableau comparatif

Type	Points forts	Points faibles
HTTP natif	Léger, standard	Verbeux, bas niveau
Jakarta REST	Moderne, flexible	Configuration initiale
Async	Performance, scalable	Complexité accrue
Quarkus	Productif, intégré	Framework spécifique

Client HTTP natif

// filepath: /home/jovyan/work/local/02_java_rest_L_client.qmd
try {
    // Configuration de la connexion
    URL url = new URL("http://localhost:9998/mylibrary");
    HttpURLConnection conn = (HttpURLConnection) url.openConnection();
    conn.setRequestMethod("GET");
    conn.setRequestProperty("Accept", "application/json");
    
    // Vérification du code de réponse
    int responseCode = conn.getResponseCode();
    if (responseCode == HttpURLConnection.HTTP_OK) {
        // Lecture de la réponse
        try (BufferedReader br = new BufferedReader(
                new InputStreamReader(conn.getInputStream(), StandardCharsets.UTF_8))) {
            StringBuilder response = new StringBuilder();
            String line;
            while ((line = br.readLine()) != null) {
                response.append(line);
            }
            System.out.println("Response: " + response.toString());
        }
    } else {
        System.err.println("Error: " + responseCode);
    }
} catch (IOException e) {
    e.printStackTrace();
} finally {
    if (conn != null) {
        conn.disconnect();
    }
}

Client Jakarta REST

• Caractéristiques principales :
  • API fluide et moderne
  • Support natif JSON/XML
  • Gestion automatique des ressources
  • Extensible via filtres et intercepteurs
• Support de la sérialisation JSON et XML :
  • Jackson, MOXy, Jettison, etc.
  • JAXB pour XML https://eclipse-ee4j.github.io/jersey.github.io/documentation/latest31x/client.html

Classes fondamentales

// 1. Client - Point d'entrée principal
Client client = ClientBuilder.newBuilder()
    .register(JacksonFeature.class)
    .build();

// 2. WebTarget - Représente une ressource REST
WebTarget target = client.target("http://api.example.com")
    .path("resources")
    .path("{id}");

// 3. Response - Contient la réponse HTTP
Response response = target.request(MediaType.APPLICATION_JSON).get();

Hiérarchie des classes principales

1. ClientBuilder
   • Factory pour créer des instances Client
   • Configuration du client (timeout, features, providers)
   • Patterns fluides pour la construction
2. Client
   • Interface principale pour les requêtes HTTP
   • Gestion du cycle de vie
   • Création de WebTarget
3. WebTarget
   • Représente une URI REST
   • Construction fluide des URLs
   • Gestion des paramètres et templates
   • Création des requêtes
4. Response
   • Encapsule la réponse HTTP
   • Accès aux headers et status
   • Lecture du corps de la réponse
   • Gestion des types génériques

Classes utilitaires importantes

// Entity - Encapsulation des données envoyées
Entity.entity(data, MediaType.APPLICATION_JSON)

// MediaType - Types MIME supportés
MediaType.APPLICATION_JSON
MediaType.APPLICATION_XML

// GenericType - Gestion des types génériques
GenericType<List<Book>> listType = new GenericType<List<Book>>() {};

Exceptions principales

try {
    // ProcessingException - Erreurs de communication
    // WebApplicationException - Erreurs HTTP (4xx, 5xx)
    // ResponseProcessingException - Erreurs de traitement
} catch (ProcessingException e) {
    // Erreur réseau ou I/O
} catch (WebApplicationException e) {
    // Erreur HTTP spécifique
} catch (ResponseProcessingException e) {
    // Erreur de désérialisation
}

Configuration Maven

%%loadFromPOM
<dependency>
    <groupId>org.glassfish.jersey.core</groupId>
    <artifactId>jersey-client</artifactId>
    <version>3.1.10</version>
</dependency>
<dependency>
    <groupId>org.glassfish.jersey.media</groupId>
    <artifactId>jersey-media-json-jackson</artifactId>
    <version>3.1.10</version>
</dependency>

GET basique

        String token = "XXX-YYY-ZZZ";
        String baseUrl = "http://localhost:9998/mylibrary";

        try (Client client = ClientBuilder.newBuilder()
                .register(JacksonFeature.class)
                .build()) {

            WebTarget baseTarget = client.target(baseUrl);

            // Initialize library
            try {
                String initResponse = baseTarget.path("library/init")
                    .request(MediaType.APPLICATION_JSON)
                    .put(Entity.entity("", MediaType.TEXT_PLAIN), String.class);
                System.out.println("Library initialized: " + initResponse);
            } catch (WebApplicationException e) {
                System.err.println("Failed to initialize library: " + e.getMessage());
            }

            // Get author
            WebTarget authorTarget = baseTarget.path("authors/{id}");
            try (Response response = authorTarget
                    .resolveTemplate("id", "1")
                    .request(MediaType.APPLICATION_JSON)
                    .header("Authorization", "Bearer " + token)
                    .get()) {

                if (response.getStatus() == Response.Status.OK.getStatusCode()) {
                    Author author = response.readEntity(Author.class);
                    System.out.println("Author: " + author);
                } else {
                    String error = response.hasEntity() ? response.readEntity(String.class) : "Unknown error";
                    System.err.printf("Error %d: %s%n", response.getStatus(), error);
                }
            }
        } catch (ProcessingException e) {
            System.err.println("Communication error: " + e.getMessage());
        }

Library initialized: 2
Author: Library.Author(id=1, name=Martin, firstname=Alfred, biography=null)

POST avec entité

Book newBook = new Book("Java REST", "John Doe");

Response response = target.request(MediaType.APPLICATION_JSON)
                         .post(Entity.entity(newBook, MediaType.APPLICATION_JSON));

// Vérification de la création
if (response.getStatus() == Response.Status.CREATED.getStatusCode()) {
    URI location = response.getLocation();
    System.out.println("Ressource créée à: " + location);
}

Un exemple de client REST

La classe fr.univtln.bruno.samples.jaxrs.client.BiblioClient présente un client qui utilise l’API fluent cliente pour construire des requêtes REST en Java.

@Log
public class BiblioClient {
    private static final String BASE_URL = "http://localhost:9998/mylibrary";
    private static final String AUTH_EMAIL = "john.doe@nowhere.com";
    private static final String AUTH_PASSWORD = "admin";
    private static final String BEARER_PREFIX = "Bearer ";
    private static final String BASIC_PREFIX = "Basic ";

    /**
     * Main method demonstrating the REST client functionality.
     * @param args command line arguments (not used)
     */
    public static void main(String[] args) {
        try (Client client = ClientBuilder.newClient()) {
            WebTarget webResource = client.target(BASE_URL);
            
            try {
                initializeLibrary(webResource);
                fetchAuthors(webResource);
                fetchAuthorById(webResource, 1);
                
                Optional<String> token = authenticate(webResource);
                token.ifPresent(t -> accessSecuredEndpoint(webResource, t));
                
            } catch (WebApplicationException e) {
                log.severe(String.format("REST API error: Status=%d, Message=%s", 
                    e.getResponse().getStatus(), 
                    e.getMessage()));
            } catch (Exception e) {
                log.severe("Unexpected error: " + e.getMessage());
            }
        }
    }

    /**
     * Initializes the library with default data.
     * @param webResource the web target for the API
     * @return initialization response message
     */
    private static String initializeLibrary(WebTarget webResource) {
        String response = webResource.path("library/init")
                .request()
                .put(Entity.entity("", MediaType.TEXT_PLAIN), String.class);
        log.info("Library initialized: " + response);
        return response;
    }

    /**
     * Fetches all authors from the library.
     * @param webResource the web target for the API
     * @return JSON string containing author data
     */
    private static String fetchAuthors(WebTarget webResource) {
        String response = webResource.path("authors")
                .request()
                .get(String.class);
        log.info("Authors: " + response);
        return response;
    }

    /**
     * Fetches a specific author by ID.
     * @param webResource the web target for the API
     * @param id the author ID
     * @return Author object
     */
    private static Library.Author fetchAuthorById(WebTarget webResource, int id) {
        Library.Author author = webResource.path("authors/" + id)
                .request()
                .get(Library.Author.class);
        log.info("Author details: " + author);
        return author;
    }

    /**
     * Authenticates with the API using Basic authentication.
     * @param webResource the web target for the API
     * @return Optional containing the JWT token if authentication successful
     */
    private static Optional<String> authenticate(WebTarget webResource) {
        try {
            String credentials = AUTH_EMAIL + ":" + AUTH_PASSWORD;
            String encodedCredentials = java.util.Base64.getEncoder()
                    .encodeToString(credentials.getBytes(StandardCharsets.UTF_8));
            
            String token = webResource.path("setup/login")
                    .request()
                    .accept(MediaType.TEXT_PLAIN)
                    .header("Authorization", BASIC_PREFIX + encodedCredentials)
                    .get(String.class);

            if (!token.isBlank()) {
                log.info("Authentication successful - token received");
                return Optional.of(token);
            }
        } catch (WebApplicationException e) {
            log.warning("Authentication failed: " + e.getMessage());
        }
        return Optional.empty();
    }

    /**
     * Accesses a secured endpoint using JWT authentication.
     * @param webResource the web target for the API
     * @param token the JWT token
     * @return response from the secured endpoint
     */
    private static String accessSecuredEndpoint(WebTarget webResource, String token) {
        String result = webResource.path("setup/secured")
                .request()
                .header("Authorization", BEARER_PREFIX + token)
                .get(String.class);
        log.info("Secured endpoint response: " + result);
        return result;
    }
}

%%shell 
cd /home/jovyan/work/src/github/ebpro/sample-jaxrs
mvn  -quiet -Dmain.class="fr.univtln.bruno.samples.jaxrs.client.BiblioClient" exec:java

Feb 25, 2025 11:19:59 AM fr.univtln.bruno.samples.jaxrs.client.BiblioClient initializeLibrary
INFO: Library initialized: 2
Feb 25, 2025 11:19:59 AM fr.univtln.bruno.samples.jaxrs.client.BiblioClient fetchAuthors
INFO: Authors: [{"id":1,"name":"Martin","firstname":"Alfred","books":[1,2]},{"id":2,"name":"Durand","firstname":"Marie","books":[2,3,4]}]
Feb 25, 2025 11:19:59 AM fr.univtln.bruno.samples.jaxrs.client.BiblioClient fetchAuthorById
INFO: Author details: Library.Author(id=1, name=Martin, firstname=Alfred, biography=null)
Feb 25, 2025 11:20:00 AM fr.univtln.bruno.samples.jaxrs.client.BiblioClient authenticate
INFO: Authentication successful - token received
Feb 25, 2025 11:20:00 AM fr.univtln.bruno.samples.jaxrs.client.BiblioClient accessSecuredEndpoint
INFO: Secured endpoint response: Access with JWT ok for Doe, John <john.doe@nowhere.com>

Client REST asynchrone

La programmation réactive avec les clients REST permet de gérer efficacement les opérations d’E/S non bloquantes, améliorant ainsi les performances des applications.

• Principes clés

  • Non-blocking I/O : Les opérations d’E/S n’immobilisent pas les threads
  • Back-pressure : Contrôle du flux de données entre producteur et consommateur
  • Scalabilité : Meilleure utilisation des ressources système
  • Résilience : Gestion améliorée des erreurs et des timeouts

Quarkus REST Client

Quarkus fournit un client REST déclaratif qui simplifie l’intégration avec les APIs REST.

https://quarkus.io/guides/rest-client