Http REST

Http REST

One of the primary reason why REST is simple to use is because REST uses HTTP as not just transport layer but as an API.

HTTP as an API

Http Methods

Any REST services can be accessed only by well-known HTTP methods

          GET   -        Retrieve

          POST -        CREATE

          PUT    -        Update

          DELETE -     Delete

You might argue the SOAP allows to have developer defined methods, whereas here it is limited to these methods. DB has only these operations but still able to meet their expectations, REST will so.

Http Errors

REST client knows about the status of their request from the traditional Http status code 

         

          100 - 199  - Information

          200 – 299 - Success

          300 – 399 - Redirection

          400 – 499 - Client Side Error

          500 – 599 - Server Error

Few of the most commonly seen codes:

          200 – OK

          400 – Bad request

          405 – Method not allowed

          500 – Internal Server Error 

A Recap - Http Servlet:

When we speak about Http methods, the first thing comes to our mind is Http Servlet where we override doGet & doPost methods. However we use these methods interchangeably but in REST it is advisable to use the appropriate method. Since Http servlet is built for http methods it is always the easiest choice to implement REST service.

REST – Representation State Transfer

The Heart of REST is “Resource”, which resides in the server whose state is transferred from client to server and vice-versa.

Resource

Each resource is unique in an application

   Can be identified by URI (uniform resource identifier)

   Can be accessed via Http Methods [GET, POST…]

Representation

A temporal state of the Resource at the time of the request, it can be of any format

     XML

     JSON

     HTML
     Or any other thing which comes in future   

           

The page you are viewing now is the current state of the article represented in html format transferred from server [blogger.com] to the client [your browser].

How is web application different from REST service? Any stateless [does not require user session], Independent web page can be said as REST implementation. Here it is represented in text/html format.

Guidelines to implement REST service

     

    1.   Identify Resources

    2.   Decide the Representation [xml, json, etc]

    3.   Define URI for the resources

    4. At last, lets worry about the implementation technology & frameworks  

  

Jersey [JAX-RS] reference implementation

Jersey [a JAX-RS implementation framework] is one of the most commonly used REST framework. 

Jersey Annotations

URI:

@Path –

a.    Declared at the class level to indicate the class [pojo] is a Resource which can identified by this URI

b.    Declared at Method level to indicate the relate path with in the Resource URI

Http Methods:

@GET

@POST

@PUT

@DELETE

URI Variables:

@PathParam

This is used together with @Path & in conjunction with @GET, @POST, @PUT, @DELETE

Variables in the URI can be read as PathParam in to method

Input & Output Formats

@Consumes

Applicable for @POST & @PUT

The input format the methods support i.e, “application/xml” here. The client will be setting the header “Content-Type” as “application/xml”   
   

 

@Produces

This works with @GET, @POST & @PUT

The client sends HTTP Request together with an Accept Http header that map directly to the content-type the method provider.

Form Param

This allows http form to be submitted to service

Exercise – Built a simple REST service & client using jersey 2

Resource:     Book

Representation: JASON

URI: /book/{bookName}

Fwk: Jersey 2

Rest Service

     1.   Built a simple webapp maven project

     

    2.   Import the  maven project into your workspace

    3. Add Jersey dependencies in project pom.xml

    

   4.  Create a simple Book Resource

      

            Here the java-jason conversion is handled by Jackson framework.

    5.   Configure rest servlet container in web.xml

    6.   Deploy the app to any j2ee container

You can choose your choice of app server.Jetty is a light weight server which I have used for testing this rest service.

Version: jetty-distribution-8.1.0.RC5

Copy the project war to jetty webapp and start the server

java –jar start.jar

   

     7.   Test the service using chrome advance rest client app

           

            URL: http://localhost:8080/LibraryRestService/mylib/book/samplebook

   Method : GET

Upon submitting the request, you should get the below Jason response

 {"name":"sampleBook","author":"xyz","publisher":"abc"}

Rest java Client

    1.   Built a simple java maven project

    

    

   2. Import the  maven project into your workspace

   3. Add Jersey client dependencies 

 

  

  4. Create client

  Here the JacksonFeature will transform the jason to java bean. 

However I had few version issues which I couldn’t resolve, hence I had to use Jackson ObjectMapper to convert Jason to java manually i.e., something similar to below

String content = target.request().get(String.class);

ObjectMapper mapper = new ObjectMapper();

Book response = mapper.readValue(content, Book.class);

  

I hope you would have got some good understanding on REST & JAX-RS/Jackson framework.  

Thank you. Hopefully I'll meet you again in my next article :)