Client REST avec Jakarta RESTful Web Services

Lecture

Java

RESTful

Web Services

Guide pratique pour créer des clients REST en Java

Auteur

Affiliations

Emmanuel BRUNO

Université de Toulon

LIS UMR CNRS 7020

Date de publication

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. En Java, Jakarta RESTful Web Services (anciennement JAX-RS) fournit une API fluide pour construire des requêtes REST de manière élégante.

Types de Clients REST

Il existe plusieurs approches pour implémenter un client REST en Java, chacune avec ses avantages et cas d’usage spécifiques :

Client HTTP natif : Utilise l’API HTTP native de Java, idéal pour les cas simples
Client Jakarta REST : Offre une API moderne et fluide, recommandé pour les applications enterprise
Client REST asynchrone : Permet des opérations non bloquantes, parfait pour la haute performance
Client Quarkus : Simplifie le développement de microservices avec une approche déclarative

Tableau comparatif

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

ClientBuilder
- Factory pour créer des instances Client
- Configuration du client (timeout, features, providers)
- Patterns fluides pour la construction
Client
- Interface principale pour les requêtes HTTP
- Gestion du cycle de vie
- Création de WebTarget
WebTarget
- Représente une URI REST
- Construction fluide des URLs
- Gestion des paramètres et templates
- Création des requêtes
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

Réutilisation

CC BY-NC 4.0