• JAX-RS is Java based standard API for REST Web Services over HTTP protocol
• REST (Representational State Transfer) is an architectural style to easily create, modify and delete resources remotely over the network.
• RESTful is typically referred as web services implementing REST architecture. Literally speaking systems conforming to the REST constraints are referred as being RESTful.
• REST is protocol agnostic.
• The basic fundamental of REST is that each and every resource is mapped to a unique URI, where a resource could be a web-page, file, image, video.
• The Resources represented by unique URIs are treated as nouns, meaning when we design our services, our URIs should not represent an action but a noun, e.g. http://example.com/api/employees is good, http://example.com/api/get-employees is not good.
• We can create, modify and delete the resources via standard HTTP verbs. i.e. GET, POST, PUT, DELETE.
• For a developer understanding: RESTful request might invoke a method on the server which would respond back in XML/JSON etc format but still those responses are treated as resources, that means there's no concept of remote procedure call in RESTful world.
• REST over HTTP is simpler than SOAP. SOAP(Simple Object Access Protocol) is based on RPC (remote procedure call) architecture style. The SOAP client uses the WSDL file of the service to convert the RPC operations into methods.

JAX-RS Kick Start Example

In the following example we are going to use JAX-RS 2.0 reference implementation Jersey 2.22.1

Steps

1. Create Maven webapp project using archetype:generate

   mvn archetype:generate
   -DgroupId=com.logicbig.example
   -DartifactId=rest-kickstart-example
   -DarchetypeArtifactId=maven-archetype-webapp
   -DinteractiveMode=false
   

2. Remove web.xml as it's not needed for servlet 3.0
3. Make changes to pom.xml: add dependencies and tomcat7 plugin to run it as embedded server.
4. Define REST application, create RestApplication by subclassing javax.ws.rs.core.Application. The loading of this class is based on ServletContainerInitializer described here. If interested you can have a look at JerseyServletContainerInitializer to see how they are doing that.
5. Optionally override Application#getClasses() in our RestApplication and return our resource classes. It is to improve some startup time . If we don't override it, a full scan of packages will be done on the client side.
6. Add HelloWorldRestService class, a very basic RESTful resource
7. Run the web application from command line: mvn clean tomcat7:run-war
8. Open your browser and put the url http://localhost:8080/rest-kickstart-example/services/hi. You should see the "Hi there!" message

Example Project

• jersey-core-server 2.22.1: Jersey core server implementation.
• jersey-container-servlet 2.22.1: Jersey core Servlet 3.x implementation.
• JDK 1.8
• Maven 3.0.4