REpresentational State Transfer
Annotations
Jersey utilise les annotations de la spécification JAX-RS. Plusieurs types d'annotations sont présentes. On pourrait les catégoriser en deux grandes catégories : Controller et Données
Controller
Les annotations "Controller" sont les annnotations qui vont permettre d'aiguiller les requêtes HTTP à travers les bonnes méthodes. Ces annotations sont seulement utilisables au dessus d'une méthode
L'annotation @GET
@GET
public Response getSomeRessource()
{
...
}
Cette methode sera atteinte lors d'une requete HTTP de type GET
L'annotation @POST
@POST
public Response createSomeRessource()
{
...
}
Cette methode sera atteinte lors d'une requete HTTP de type POST
L'annotation @UPDATE
@UPDATE
public Response updateSomeRessource()
{
...
}
Cette methode sera atteinte lors d'une requete HTTP de type UPDATE
L'annotation @DELETE
@DELETE
public Response deleteSomeRessource()
{
...
}
Cette methode sera atteinte lors d'une requete HTTP de type DELETE
L'annotation @Path
Cette annotation peut être utilisée au dessus d'une classe pour spécifier une ressource racine
@Path("/book")
public class Book {
....
}
Mais aussi au dessus d'une méthode de la ressource racine afin de spécifier une "sous catégorie" de cette ressource
@Path("/book")
public class Book {
@GET
@Path("/fantasy")
public Response getFantasyBooks() {}
}
Dans l'exemple ci desuss, la méthode sera atteinte lors d'un appel HTTP GET a l'url /book/fantasy et aura pour but de renvoyer tous les livres dont le genre est "fantasy"
Données
Les annotations "Données" qui permettent de spécifier le format d'échange accepté par l'application. Cest annotations permettent aussi de récupérer des informations contenues dans les headers HTTP
L'annotation @Consummes
L'annotation @Consummes permet de spécifier le format de données qui va être "consommé" par le web service. Il s'agit donc du format d'entrée des données.
@Consummes(MediaType.APPLICATION_JSON)
public Response consumeJSONMethod(){ ... }
L'exemple ci dessus permet de spécifier que le format d'entrée sera du JSON. L'annotation @Consummes est le plus souvent utilisé avec les méthodes GET ( Read )
L'annotation @Produces
L'annotation @Produces permet de sécifier le format de données qui va être "produit" par le web service. Il s'agit donc du format de sortie des données
@Produces(MediaType.APPLICATION_XML)
public Response consumeJSONMethod(){ ... }
L'exemple ci dessus permet de spécifier que le format de sortie sera du XML. L'annotation @Produces est le plus utilisé avec les méthodes POST - UPDATE - DELETE
Plusieurs formats d'échanges sont possibles : Ils sont contenus dans la classe MediaType.
Code de retour
Le protocole HTTP utilise des codes de retour qui permettent d'informer le client sur l'état d'une action ( exemple : 404 Not Found). Lors de la création d'un service REST, nous avons besoin de pouvoir envoyer ces codes de retours. Ceci ce fait par l'intermédiaire de la Classe Response La methode status permet de spécifier un code de retour. Ceux ci sont contenus dans l'énumération Status
return Response.status(Status.OK).build();
Le code ci dessus permet de renvoyer un code HTTP 200 (OK) au client lui indiquant que l'action s'est déroulée avec succès.