REST

Rapide introduction à JAX-RS, spécification de Jakarta EE pour l'écriture d'une application REST, en utilisant le code généré par IntelliJ IDEA.

Code généré

Examinez le code généré par l'IDE. 2 classes Java ont été créées, HelloApplication et HelloResource, écrites selon la spécification JAX-RS de Jakarta EE :

• HelloApplication sert à configurer l'application REST. Cette classe définit la racine des URLs pour lancer des requêtes vers les ressources REST de l'application (valeur "api" de l'annotation @ApplicationPath). On pourrait y ajouter d'autres configurations pour REST.
• La classe de ressource HelloResource définit une ressource REST, un des endpoints de l'application.

Classe HelloResource :

@Path("/hello-world")
public class HelloResource {
    
    @GET
    @Produces("text/plain")
    public String hello(){
        return "Hello, World!";
    }
}

L'annotation @Path("/hello-world") indique que la classe traitera les requêtes REST vers les URL de racine http://localhost:8080/<context path>/api/hello-world.

• <context-path> désigne le contexte de l'application qu'il faut remplacer par sa valeur, Par défaut, ce contexte est le nom du fichier war de l'application avec la version accolée en suffixe ; vous pouvez le voir en allant dans le menu Run > Edit Configurations..., par exemple, http://localhost:8080/tp3Xxxxx-1.0-SNAPSHOT/.
• "api" vient de la classe HelloApplication.

L'annotation @GET indique que la méthode hello() sera exécutée pour traiter les requêtes HTTP GET. Le code de cette méthode retourne une réponse HTTP avec le contenu "ping Jakarta EE" et le statut "OK", de code 200, qui indique que la requête a été traitée et que tout s'est bien passé.

L'annotation @Produces("text/plain") indique que la méthode retourne un simple texte. Le plus souvent, les méthodes de ressources retournent du JSON et dans ce cas elles sont annotées par @Produces("application/json")

Test du code

Vérifiez que la configuration d'exécution est correcte : menu RUN > Edit configurations... Vérifiez le serveur, la version de Java, la construction du fichier war et son déploiement. Profitez-en pour changer le nom de la configuration (par exemple "TP3 REST").

Démarrez l'application, ce qui démarre le serveur d'application. Une nouvelle page va s'ouvrir dans le navigateur avec une erreur 404. Cette erreur est normale car l'application n'a pas de page HTML ni de page JSF. Remarquez l'URL ; c'est une autre façon de voir le contexte de l'application.

Pour voir REST en action, changez cet l'URL du navigateur pour ajouter à la fin api/hello-world. Une requête GET est envoyée au serveur. "Hello, World!" devrait s'afficher en réponse.

Vous pouvez changer certaines des valeurs des 2 classes REST pour voir si vous avez compris. Il faut redéployer l'application à chaque modification.

S'il est installé sur votre ordinateur, vous pouvez aussi tester avec curl. Tapez la commande

ou bien, pour avoir plus d'information sur la requête et la réponse :

curl -v http://localhost:8080/<context path>/api/hello-world

Modification du code

Ajouter un paramètre à la méthode hello

Vous allez ajouter un paramètre à la méthode hello. La valeur de ce paramètre sera donnée dans l'URL : quand une requête GET sera envoyée avec l'URL ".../api/hello-world/personnes/Mohamed" , une page Web s'ouvre et affiche "Hello, Mohamed". Pour une "vraie" application REST, cette page devrait sans doute afficher des informations sur la personne nommée Mohamed ; cette application veut juste vous montrer des points sur JAX-RS qui vous seront utiles pour ce TP.

Pour cela, il va falloir modifier la méthode hello :

• Ajouter une annotation @Path("personnes/{nom}") ; cette annotation indique que la méthode sera appelée avec un URL de type ".../api/hello/personnes/Mohamed".
• Ajouter un paramètre à la méthode et indiquer que sa valeur sera donnée dans l'URL. Sa valeur sera, par exemple, "Mohamed" avec l'URL ci-dessus. Pour cela il faut annoter le paramètre par @PathParam("nom") ("nom" doit correspondre à l'annotation de la méthode).

Test du code.

Si tout va bien commit et push.

Type retour Response

Si vous changez le type retour de la méthode hello en jakarta.ws.rs.core.Response, vous pourrez donner plus d'informations au client HTTP : code retour, headers, cookies,...

Voici un exemple de code pour retourner la même réponse, avec le statut "ok" :
return Response.ok("Hello, " + nom).build();

Testez.