An Introduction to JAX-RS Annotations (Part 1)

gowebing

The JAX-RS API forms an important part of the Java EE platform's commitment to providing standards-driven technology. The ubiquitous nature of the Internet and that recent increasing interest in the microservice architecture has put more focus on small, scalable, autonomous services and their interoperability. The principal methodology used to allow microservices to communicate with each other and the ‘outside world’ is REST and its use in developing RESTful APIs. The technology that Java EE provides for this is the JAX-RS: Java API for RESTful Web Services.

The Goals of JAX-RS

The goals of the JAX-RS API are:

Overview of JAX-RS Annotations

Annotations in the JAX-RS API are used to provide meta-data around the web resource. A typical example is to use the @GET annotation with the @Path annotation to identify the method that should handle a GET request to the specified URI in the @Path annotation.

What follows is a very quick overview of the annotations available to mark the methods and classes used to construct web resources. This is not an exhaustive list, there are a few more annotations in the JAR-RS arsenal, however, as the majority of the work of JAX-RS is in configuration and handling web resources, this is where you will find the majority of the API's annotations put to use.

This is the first in a three-part series looking at JAX-RS annotations.

Part two covers:

Part three covers:

Let’s get started.

The @ApplicationPath Annotation

Let’s start at the top of the trees with the @ApplicationPath annotation:

@ApplicationPath("/api")
public class RESTConfig extends Application {}


This is where you start defining the URI to your resources. Here we are saying that all our resources are to be found at the root /api. The URL should look something like this: http://localhost:8080/webcontext/api/ where webcontext is the name of your application.

The @Path Annotation

Next, comes the URI path to the resource. In a bookshop application, this might be /books/.

@Path("/books")
public class BookResource {}


Now, the URI to the book resource is /api/books and the URL would be http://localhost:8080/webcontext/api/books. It is the convention to name the resource as a noun and in the plural.

Once the path to our resource has been defined the individual resource method are configured for the HTTP method and context type. This is where the fun begins.

There is an annotation for each of the HTTP methods.

The @GET HTTP Method Annotation

Methods annotation with the @GET annotation respond to HTTP get requests.

@GET
@Produces(MediaType.APPLICATION_JSON)
public Response getAllBooks() {
    List<Book> books = BookRepository.getAllBooks(); // queries database for all books
    GenericEntity<List<Book>> list = new GenericEntity<List<Book>>(books) {};
    return Response.ok(list).build();
}


Note that the GenericEntity wrapper is used to maintain the generic type of the List as Book.

The @POST HTTP Method Annotation

Methods annotated @POST respond to POST method requests.

@POST
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public Response saveBook(Book book) {
    book = bookRepository.saveBook(book);
    return Response.ok(book).build();
}


The POST HTTP method is commonly used to create a resource. This example code persists the new book object in the database.

The @PUT HTTP Method Annotation

The @PUT annotation is used for updating a record and method annotated this way respond to an HTTP PUT request.

@PUT
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public Response updateBook(Book book) {
    book = bookRepository.updateBook(book);
    return Response.ok(book).build();
}


The @DELETE HTTP Method Annotation

Methods annotated @DELETE are expected to delete a resource.

@DELETE
@Path("{isbn}")
@Produces(MediaType.APPLICATION_JSON)
public Response deleteBook(@PathParam("isbn") String isbn) {
    Book book = bookRepository.deleteBookByIsbn(isbn);
    return Response.ok(book).build();
}


Usually, the resource or its id is passed to the resource method parameter from the URI variable as you can see in this example.

The @OPTIONS HTTP Method Annotation

Methods annotated with @OPTIONS respond to HTTP Option requests.

@OPTIONS
public Response preflight() {
    return Response.ok().header("Allow", true).build();
}


The options method is used as a request when the client wishes to make a complex HTTP request to a different domain. It is done in order to determine if the client is allowed to make the request or not.

The @HEAD HTTP Method Annotation

The HTTP HEAD method is identical to HTTP GET method except that the server mustn’t respond with a body in the response.

@HEAD
public Response headsUp() {
    return Response.ok().build();
}


This method is to obtain meta-data regarding the entity without sending back the entity body itself.

Code Repository

The source code for this article is in my GitHub repository. Code for all my articles is in the ReadLearnCode Articles repository.

What Next?

That is it for part one, coming up next is part two where you will learn more about the annotations used to make RESTful web endpoints.

Further Reading

I have published more articles about JAX-RS which I hope you find interesting:

 

 

 

 

Top