Skip to main content

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 the 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 the 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 the real world we will be developing an API for either Resources or Non-Resources items. Usually, a standard API URL looks like the below for Resources:

Get a list of all humans - https://localhost:8080/humans

Get a specific human - https://localhost:8080/humans**/40200/**

Get a list of all addresses of a specific human - https://localhost:8080/humans**/40200/addresses/**

Get a specific address of a specific human - https://localhost:8080/humans**/40200/addresses/2/**

Note: Other than the 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 say Address Resources is Sub Resources of Human Resources. We may represent Address Resources as independent Resources as well as Sub Resources. When we design API for representing relationship data we opt for Sub Resources.

Tip: Resources like the Humans in the 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 https://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 the 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 https://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 https://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 https://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 express the expected values using regular expression in @Path.

For e.g. if we wanted to only accept numbers for human id then 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 https://localhost:8080/humans/40200

Test /human/40200 API called successfully.

If we access the URL https://localhost:8080/humans/40200abc ; It will give you an 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 don't make any difference.

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

Jersey Resource SubResource @Path @PathParam

Download the Full Project

Follow Project On Github

Comments

Popular posts from this blog

Working with request header in Jersey (JAX-RS) guide

In the  previous post , we talked about, how to get parameters and their values from the request query string. In this guide learn how to get request header values in Jersey (JAX-RS) based application. We had tested or used the following tools and technologies in this project: Jersey (v 2.21) Gradle Build System (v 2.9) Spring Boot (v 1.3) Java (v 1.8) Eclipse IDE This is a part of  Jersey (JAX-RS) Restful Web Services Development Guides series. Please read Jersey + Spring Boot getting started guide . Gradle Build File We are using Gradle for our build and dependency management (Using Maven rather than Gradle is a very trivial task). File: build.gradle buildscript { ext { springBootVersion = '1.3.0.RELEASE' } repositories { mavenCentral() } dependencies { classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}") } } apply plugin: 'java' apply plugin: 'eclipse' a

Ajax Cross Domain Resource Access Using jQuery

Some time back in our project we faced a problem while making an Ajax call using jQuery. Chrome Browser console had given some weird error message like below when we try to access one of our web pages: When we try to access the same web page in the Firefox browser, it doesn't give any error in the console but some parsing error occurred. In our case, we were accessing XML as an Ajax request resource. I was curious to check if the non-XML cross-domain resource was successfully loading or not. But finally, I realized that it is not going through. jersey-spring-boot-quick-starter-guide In our Ajax call, requesting domain was not the same as the requested URL domain. $.ajax({ url: "https://10.11.2.171:81/xxxxxx/xxxxxxx.xml" , type : "get" , success: function (response) { alert( "Load was performed." ); }, error : function (xhr, status) {

FastAPI first shot

Setup on my Mac (Macbook Pro 15 inch Retina, Mid 2014) Prerequisite Python 3.6+ (I used 3.7.x. I recently reinstalled OS after cleaning up disk, where stock Python 2.7 was available. I installed Pyenv and then used it to install 3.7.x). I already had a git repo initialized at Github for this project. I checked that out. I use this approach to keep all the source code safe or at a specific place 😀. I set the Python version in .python-version file. I also initialize the virtual environment using pyenv in venv folder. I started the virtual environment. FastAPI specific dependencies setup Now I started with basic pip commands to install dependency for the project. I saved dependencies in requirements.txt  the file. Minimal viable code to spin an API Server FastAPI is as cool as NodeJS or Go Lang (?) to demonstrate the ability to spin an API endpoint up and running in no time. I had the same feeling for the Flask too, which was also super cool. app/main.py: from typing i