Jersey is the most popular framework for implementing RESTful web services in Java. Jersey provides support for JAX-RS APIs (https://jax-rs-spec.java.net/
Recently, RESTful web services have been seen as a major breakthrough for organizations which have been striving for less efforts & more productivity from the web services perspective. It delivers high throughput as the same service can be re-used for multiple functionalities with minimum or no changes at all.
This is possible because in a REST (Representational State Transfer) based architecture, everything is treated as a resource and web services are built around these resources to perform needed operations.
Eg: "User" is a resource in REST & we can implement web services on this "User" resource as follows :
GET /users => Return a list of all users
GET /users/{id} => Return a single record with specified id
DELETE /users/{id} => Delete a user with specified id
REST relies on HTTP methods to identify & distinguish various operations such as GET & DELETE as shown in the above example.
The HTTP methods are as follows :
GET => to get a resource
POST => to create a new resource
PUT => to update an existing resource
DELETE => to delete an existing resource
The GET method always performs read-only operations. In our example, GET /users reads & returns a list of all users. Since nothing is created or updated on the server this is a read-only operation and can be called multiple times without affecting any resource.
Whereas in case of POST, PUT & DELETE something is created, updated or deleted on the server. Let say, the email address of the user with id 35 is updated with PUT /users/35. Now if the same call is repeated it would simply rewrite the same email address to the user 35. So we can say that it is safe to call the PUT method multiple times. If we delete the user with DELETE /users/35 it would initially remove the user record from the server. Now if we repeat the same operation, the server would simply perform nothing as there's no resource available to delete. So we can say that it is safe to call DELETE method multiple times.
If we create a new user with POST /users then a new record for the user would be created. And if we repeat this call, a new record would be created AGAIN! So every repeated call would create new user record!
HTTP/1.1 specification (https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html) states this property as "idempotence" where the side-effect of repeated calls is the same as that of a single call. GET, PUT & DELETE are idempotent whereas POST is non-idempotent.
Now you'd be wondering why we're discussing idempotence. Well, almost all of the web browsers are implemented in such a way that if any non-idempotent request is called from the browser and if the user clicks "refresh" or "retry" then the browser warns the user of the duplicate request. A very familiar example would be that of an online payment transaction where the browser warns the user of the duplicate request and on confirmation the user might end up paying twice for a single order.
Thus the above mentioned HTTP method standards should be followed to access any resource in the REST based architecture.
Jersey is a reference implementation of the JAX-RS (JSR 311 & JSR 339) specification. This specification defines standard annotations to be used to enable support for RESTful web services throughout various java application servers such as Tomcat & Glassfish.
The annotations are as follows :
@PATH => defines the relative path for the resource
@GET => indicates that the annotated method responds to HTTP GET requests
@PUT => indicates that the annotated method responds to HTTP PUT requests
@DELETE => indicates that the annotated method responds to HTTP DELETE requests
@POST => indicates that the annotated method responds to HTTP POST requests
@HEAD => indicates that the annotated method responds to HTTP HEAD requests
@OPTIONS => indicates that the annotated method responds to HTTP OPTIONS requests
@Produces => MIME media types of the response like json & xml
@Consumes => MIME media types of the request like json & xml
@PathParam => represents the parameter from the URI path
In GET users/35, 35 is the id to extract using PathParam
@QueryParam => represents the parameter from the query string
In GET users/35?type=fb, fb is the query parameter to extract using QueryParam
@FormParam => represents the parameter from a user submitted form
@CookieParam => represents the parameter from a cookie
@HeaderParam => represents the parameter from the request header
By using the above annotations it becomes very easy to implement & maintain RESTful web services.
Recently, RESTful web services have been seen as a major breakthrough for organizations which have been striving for less efforts & more productivity from the web services perspective. It delivers high throughput as the same service can be re-used for multiple functionalities with minimum or no changes at all.
This is possible because in a REST (Representational State Transfer) based architecture, everything is treated as a resource and web services are built around these resources to perform needed operations.
Eg: "User" is a resource in REST & we can implement web services on this "User" resource as follows :
GET /users => Return a list of all users
GET /users/{id} => Return a single record with specified id
DELETE /users/{id} => Delete a user with specified id
REST relies on HTTP methods to identify & distinguish various operations such as GET & DELETE as shown in the above example.
The HTTP methods are as follows :
GET => to get a resource
POST => to create a new resource
PUT => to update an existing resource
DELETE => to delete an existing resource
The GET method always performs read-only operations. In our example, GET /users reads & returns a list of all users. Since nothing is created or updated on the server this is a read-only operation and can be called multiple times without affecting any resource.
Whereas in case of POST, PUT & DELETE something is created, updated or deleted on the server. Let say, the email address of the user with id 35 is updated with PUT /users/35. Now if the same call is repeated it would simply rewrite the same email address to the user 35. So we can say that it is safe to call the PUT method multiple times. If we delete the user with DELETE /users/35 it would initially remove the user record from the server. Now if we repeat the same operation, the server would simply perform nothing as there's no resource available to delete. So we can say that it is safe to call DELETE method multiple times.
If we create a new user with POST /users then a new record for the user would be created. And if we repeat this call, a new record would be created AGAIN! So every repeated call would create new user record!
HTTP/1.1 specification (https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html) states this property as "idempotence" where the side-effect of repeated calls is the same as that of a single call. GET, PUT & DELETE are idempotent whereas POST is non-idempotent.
Now you'd be wondering why we're discussing idempotence. Well, almost all of the web browsers are implemented in such a way that if any non-idempotent request is called from the browser and if the user clicks "refresh" or "retry" then the browser warns the user of the duplicate request. A very familiar example would be that of an online payment transaction where the browser warns the user of the duplicate request and on confirmation the user might end up paying twice for a single order.
Thus the above mentioned HTTP method standards should be followed to access any resource in the REST based architecture.
Jersey is a reference implementation of the JAX-RS (JSR 311 & JSR 339) specification. This specification defines standard annotations to be used to enable support for RESTful web services throughout various java application servers such as Tomcat & Glassfish.
The annotations are as follows :
@PATH => defines the relative path for the resource
@GET => indicates that the annotated method responds to HTTP GET requests
@PUT => indicates that the annotated method responds to HTTP PUT requests
@DELETE => indicates that the annotated method responds to HTTP DELETE requests
@POST => indicates that the annotated method responds to HTTP POST requests
@HEAD => indicates that the annotated method responds to HTTP HEAD requests
@OPTIONS => indicates that the annotated method responds to HTTP OPTIONS requests
@Produces => MIME media types of the response like json & xml
@Consumes => MIME media types of the request like json & xml
@PathParam => represents the parameter from the URI path
In GET users/35, 35 is the id to extract using PathParam
@QueryParam => represents the parameter from the query string
In GET users/35?type=fb, fb is the query parameter to extract using QueryParam
@FormParam => represents the parameter from a user submitted form
@CookieParam => represents the parameter from a cookie
@HeaderParam => represents the parameter from the request header
By using the above annotations it becomes very easy to implement & maintain RESTful web services.
