Jersey (JAX-RS) Resources URI mapping with @Path

In this guide we will learn Jersey(JAX-RS) Resources and Sub Resources concepts as well as mapping of API HTTP URI using @Path annotation. Specifically we will go through following concepts and examples:

  1. Root Resources (Resources)
  2. Sub Resources
  3. HTTP URL mapping to Resources and Sub Resources using @Path annotation
  4. Deep dive @Path annotation
  5. Understand @PathParam annotation

We had tested or used following tools and technologies in this project:

  1. Jersey (v 2.21)
  2. Gradle Build System (v 2.9)
  3. Spring Boot (v 1.3)
  4. Java (v 1.8)
  5. Eclipse IDE

This is a part of Jersey (JAX-RS) Restful Web Services Development Guides series. Please read Jersey + Spring Boot getting started guide.

Understand Resources & Sub Resources

In real world we will be developing API for either Resources or Non Resources items. Usually a standard API URLs looks like below for Resources:

Get a list of all humans –
http://localhost:8080/humans

Get a specific human –
http://localhost:8080/humans/40200/

Get a list of all addresses of a specific human –
http://localhost:8080/humans/40200/addresses/

Get a specific address of a specific human –
http://localhost:8080/humans/40200/addresses/2/

Note: Other than bold part everything is base URI.

In the above examples, We are talking about Human Resources. Human Resources has relation with Address Resources. Or We may can say Address Resources is Sub Resources of Human Resources. We may can represent Address Resources as an independent Resources as well as Sub Resources. When we design API for representing relationship data we opt for Sub Resources.

Tip: Resources like Humans in above example can also be called Root Resources.

Let’s understand, how we can map Resources and Sub Resources to URI

Examples Resource & Sub Resource URI mapping using @Path

Resource class level URI mapping using @Path

Mapping /Humans

File: HumansResource.java

package in.geekmj.jersey.resource;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.Response;

@Path("Humans")
public class HumansResource {

	/**
	 * 
	 * @return Response
	 */
	@GET
	@Produces("text/plain")
	public Response getHumans() {

		return Response.accepted("Test /Human api called successfully.").build();
	}
}

Access url http://localhost:8080/Humans

Test /human api called successfully.

Like @GET we can also use @POST, @PUT and @DELETE.

Read URI Path Parameter using @PathParam

Mapping /humans/40200 or /humans/123445 or /humans/ and extracting humanId from path and using it in method with the help of @PathParam annotation.

File: HumansResource.java

package in.geekmj.jersey.resource;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.Response;

@Path("humans")
public class HumansResource {

	@GET
	@Path("{humanId}")
	@Produces("text/plain")
	public Response getHuman(@PathParam("humanId") int humanId) {

		return Response.accepted("Test /human/" + humanId + " api called successfully.").build();
	}
}

Access URL http://localhost:8080/humans/40200

Test /human/40200 api called successfully.

Sub Resources URI Mapping using @Path at method level

Mapping /humans/123442/addresses

File: HumansResource.java

package in.geekmj.jersey.resource;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.Response;

@Path("humans")
public class HumansResource {

	@GET
	@Path("{humanId}/addresses")
	@Produces("text/plain")
	public Response getAddresses(@PathParam("humanId") int humanId) {

		return Response.accepted("Test /human/" + humanId + "/addresses api called successfully.").build();
	}
}

Access url http://localhost:8080/humans/40200/addresses

Test /humans/40200/addresses api called successfully.

Read Sub Resource URI Path Parameter using @PathParam

Mapping /humans/123442/addresses/2

File: HumansResource.java

package in.geekmj.jersey.resource;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.Response;

@Path("humans")
public class HumansResource {

	@GET
	@Path("{humanId}/addresses/{addressId}")
	@Produces("text/plain")
	public Response getAddress(@PathParam("humanId") int humanId, @PathParam("addressId") int addressId) {

		return Response.accepted(
				"Test /human/" + humanId + "/addresses/addresses/" + addressId + " api called successfully.")
				.build();
	}
}

Access url http://localhost:8080/humans/40200/addresses/2

Test /humans/40200/addresses/2 api called successfully.

Validate path parameter with Regular Expression in @Path

If we wanted to confirm the path parameter(s) value we may can express the expected values using regular expression in @Path.

For e.g. if we wanted to only accept numbers for human id than we express that like @Path(“humans/{humanId: [0-9]*}”)

File: HumansResource.java

package in.geekmj.jersey.resource;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.Response;

@Path("humans")
public class HumansResource {

	@GET
	@Path("{humanId: [0-9]*}")
	@Produces("text/plain")
	public Response getHuman(@PathParam("humanId") int humanId) {

		return Response.accepted("Test /human/" + humanId + " api called successfully.").build();
	}
}

Access url http://localhost:8080/humans/40200

Test /human/40200 api called successfully.

If we access url http://localhost:8080/humans/40200abc ; It will give you HTTP 404 error.

Tip: Default Regular Expression is {pathParam: [^/]+}. You can use any regular expression to confirm the Path Parameter values.

Another Tip: We are free to use or not use beginning / (forward slash) in URI. They doesn’t make any difference.

Infographics to remember what we talked in this guide (Read Employee as Human):

Jersey Resource SubResource @Path @PathParam

Jersey Resource SubResource @Path @PathParam

Download Icon SmallDownload the Full ProjectGithub IconFollow Project On Github

Leave a Reply

Your email address will not be published. Required fields are marked *