When we create a RESTful service end-point, the first step is to define the resources (also referred as defining RESTful API). We do that by creating the unique intuitive URIs (intuitive because they are exposed as our service API). We should consider following key points when defining resources:
A RESTful resource is made available as an unique URI which should be represented as noun (a thing) rather than a verb (an action). Noun has some properties (and actions do not). Requesting a RESTful resource returns the properties of the thing we are interested in.
Most of the times, one resource is exposed as two URIs.
The resource collection URI, e.g. http://example.com/api/orders, which will return a collection of all orders. Plural form should be used i.e. orders instead of order.
A specific resource URI from the collection e.g. http://example.com/api/orders/345. In this example, the number 345 represents the unique id of a particular order. We can also use nested resources, for example http://example.com/api/orders/345/items/454.
Using JAX-RS Annotations to Create Resources
@ApplicationPath: This annotation identifies the application path that serves as the base URI for all resources. This should be used on the configuration class, i.e. the subclass of javax.ws.rs.core.Application. Let's use @ApplicationPath for our example resource, http://example.com/api/orders:
@ApplicationPath("api")
public class MyRestApp extends Application {
}
@Path: Identifies the URI path that a resource class or class method will serve requests for. That means we have to create a class annotated with @Path and define relative path to base URI (specified on Application class).
A resource class, annotated with @Path, is termed as
root resource class and a method of a resource class which is used to handle requests and is also annotated with @Path is termed as
sub-resource method.
In our example resource, http://example.com/api/orders, the annotation should be specified as:
@Path("/orders")
public class Order {
@GET
public String getOrders() {
return "returning all orders";
}
}
The annotation @Path can also be on method level, but the good practice is, it should be on class level if the resource represents a root collection. The method getOrders (we can give any name to this method) will get called when an HTTP GET request is made for http://example.com/api/orders. Defining multiple methods having same HTTP verb (@GET in this example) and having same resource path will result in runtime error. Note that we are just returning string from our resource method (to keep the things simple for now). In a real application the response would be in JSON, XML etc.
@PathParam : This annotation is used to extract the value of a URI template variables. A URI template is a URI-like String that contains variables enclosed by braces {}. We use URI template for varying part of URI. For example http://example.com/api/orders/345 can be mapped to http://example.com/api/orders/{orderId}. Let's define another method in our example to see how URI template can be used.
@Path("/orders")
public class Order {
@GET
public String getOrders() {
return "returning all orders";
}
@GET
@Path("{orderId}")
public String getOrderById(
@PathParam("orderId") String orderId) {
return "return order with id " + orderId;
}
}
The request http://example.com/api/orders/345 will return "returning order with id 345".
There's an automatic conversion of type for the parameters annotated with @PathParam. Following Java type are supported for conversion:
Java Primitive type
Number wrappers (generally speaking any class, having a static method: ValueOf(String))
Any class that accepts a single String argument in it's constructor.
