JAX-RS Specifications


JAX-RS: Java API for Restful web services

It’s a Java API specification which uses Java SE 5 annotations (JSR 311 specifications) for creating web services according to the REST architectural style.

Some of the annotations provided by JAX-RS to map java class as a web Resource are listed below

@Path

Specifies the relative Path of the resource.
This relative path should be specified by the client to invoke the Rest service.

@GET,@POST,@PUT,@DELETE etc specifies HTTP methods to request a resource.
Each HTTP method specifies the action to be performed with the Rest service.

@Produces

Specifies the MIME type or data representation that service is returning to the client
MIME type could be Json,xml,pdf etc.
Rest service can return data of specified MIME type to the client.

@Consumes

Specifies the MIME type or data representation that Service can accept from the client
MIME type could be Json,xml,pdf etc.
Rest service can only accept the data of specified MIME type.

Some of the annotations used at the method parameters to get the information from the request are listed below


@PathParam

This is used to bind the @Path variable value to the method parameter.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@Path("/userInfo")
public class RestServicePathParamExample {
    
    @GET
    @Path("{name}/{country}")
    @Produces("text/html")
    public Response getUserInfo(
                    @PathParam("name") String name,
                    @PathParam("country") String country) {
        
        String userDetails = User name -> "+name+", Country -> "+country+"";
        return Response.status(200).entity(userDetails).build();
 
    }
}
@Path("/userInfo")
public class RestServicePathParamExample {
    
    @GET
    @Path("{name}/{country}")
    @Produces("text/html")
    public Response getUserInfo(
                    @PathParam("name") String name,
                    @PathParam("country") String country) {
        
        String userDetails = User name -> "+name+", Country -> "+country+"";
        return Response.status(200).entity(userDetails).build();
 
    }
}

we have retrieved name and country from Path url using @PathParam and setting them to the method parameter.

@QueryParam

This is used to bind the query parameter value to the method parameter

Query string will be in the URL after ? as below
?firstName=Ram&lastName=Raj

firstName and lastName in the query param can bind with method parameters as below

1
2
3
4
5
6
7
8
9
10
11
12
13
@Path("/userInfo")
public class RestServiceQueryParamExample {
    @GET
    @Path("/getData")
    @Produces("application/json")
    public Student getUserInfo(@QueryParam("firstName") String firstName,
            @QueryParam("lastName") String lastName) {
        User user = new User();
        user.setFirstName(firstName);
        user.setLastName(lastName);
        return user;
    }
} 
@Path("/userInfo")
public class RestServiceQueryParamExample {
	@GET
	@Path("/getData")
	@Produces("application/json")
	public Student getUserInfo(@QueryParam("firstName") String firstName,
			@QueryParam("lastName") String lastName) {
		User user = new User();
		user.setFirstName(firstName);
		user.setLastName(lastName);
		return user;
	}
} 

we have used @QueryParam to retrieve firstName and lastName from query string passed as part of URL.

@MatrixParam

This is used to bind the value of HTTP matrix parameter to the method parameter.

We can find Matrix parameters in the URL separated by semicolon.

Example:
firstName=Ram;lastName=Raj

1
2
3
4
5
6
7
8
9
10
11
12
13
@Path("/userInfo")
public class RestServiceMatrixParamExample {
    @GET
    @Path("/getData")
    @Produces("application/json")
    public Student getUserInfo(@MatrixParam("firstName") String firstName,
            @MatrixParam("lastName") String lastName) {
        User user = new User();
        user.setFirstName(firstName);
        user.setLastName(lastName);
        return user;
    }
}
@Path("/userInfo")
public class RestServiceMatrixParamExample {
	@GET
	@Path("/getData")
	@Produces("application/json")
	public Student getUserInfo(@MatrixParam("firstName") String firstName,
			@MatrixParam("lastName") String lastName) {
		User user = new User();
		user.setFirstName(firstName);
		user.setLastName(lastName);
		return user;
	}
}

We have used @MatrixParam to retrieve the values passed as Matrix parameters in the URL.

@HeaderParam

This is used to bind the header value to the method parameter.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
@Path("/userInfo")
public class RestServiceHeaderParamExample {
    @GET
    @Path("/getData")
    @Produces("application/json")
    public Student getUserInfo(@HeaderParam("accessId") String accessId) {
        User user = new User();
        user.setFirstName(firstName);
        user.setLastName(lastName);
        user.setCredential(accessId);
        return user;
    }
}
@Path("/userInfo")
public class RestServiceHeaderParamExample {
	@GET
	@Path("/getData")
	@Produces("application/json")
	public Student getUserInfo(@HeaderParam("accessId") String accessId) {
		User user = new User();
		user.setFirstName(firstName);
		user.setLastName(lastName);
		user.setCredential(accessId);
		return user;
	}
}

Header parameter called accessId is retrieved using @HeaderParam and setting it to the method parameter

@CookieParam

This is used to bind the cookie value to the method parameter.

Cookie is mostly used to maintain the state between the client and server.

Example:

1
2
3
4
5
6
7
8
9
10
11
@Path("/userInfo")
public class RestServiceCookieParamExample {
    @GET
    @Path("/getData")
    @Produces("application/json")
    public Student getUserInfo(@CookieParam("userName") String userName) {
        User user = new User();
        user.setUserName(userName);
        return user;
    }
}
@Path("/userInfo")
public class RestServiceCookieParamExample {
	@GET
	@Path("/getData")
	@Produces("application/json")
	public Student getUserInfo(@CookieParam("userName") String userName) {
		User user = new User();
		user.setUserName(userName);
		return user;
	}
}

We have accessed the userName stored in cookie using @CookieParam and setting it to the method parameter.

These annotations are just the specification provided by JAX-RS which does not have any implementation by itself.

Some of the Implementations of these JAX-RS annotations are as below


Jersey

RestEasy

Restlet

Apache CXF

All the above implementations provide the libraries to support the JSR 311 specifications.

We can use any one of these implementations to develop the Rest web service

About the Author

Karibasappa G C (KB)
Founder of javainsimpleway.com
I love Java and open source technologies and very much passionate about software development.
I like to share my knowledge with others especially on technology 🙂
I have given all the examples as simple as possible to understand for the beginners.
All the code posted on my blog is developed,compiled and tested in my development environment.
If you find any mistakes or bugs, Please drop an email to kb.knowledge.sharing@gmail.com

Connect with me on Facebook for more updates

Share this article on