What is JSON and its features ?

JSON stands for JavaScript Object Notation and used to transfer data between server and client (similar to XML)

Example

employee = {

   "empId" : "143011",

   "name" : "Shaan",

   "age" :  "31"

};

JSON features

• Light-weight
• Useful when data needs to loaded quickly and asynchronously (i.e. using AJAX)
• Standard structure
• Easy to write code as a standard format expected in program
• Language independent
• works well with modern programming languages
• Easier to change server-side language without changing data format
• Easy to read & write
• Text based, human readable

JSON vs. XML

JSON is much more light-weight than XML.

JSON support usage of arrays which is not available in XML.

JSON example

{"employees":[

   {"empId":"143011", "name":"Shaan", "city":"Jhansi"},

   {"empId":"143012", "name":"Rahul", "city":"Agra"},

   {"empId":"143013", "name":"Jatin", "city":"Paris"},

]}

XML example

<employees>

  <employee>

    <empId>143011</empId>

    <name>Shaan</name>

    <city>Jhansi</city>

  </employee>

  <employee>

    <empId>143012</empId>

    <name>Rahul</name>

    <city>Agra</city>

  </employee>

  <employee>

    <empId>143013</empId>

    <name>Jatin</name>

    <city>Paris</city>

  </employee>

</employees>

What are the guidelines to develop the REST API ?

1. Do not use GET method to change the data

  GET /users/101/enable

  GET /users/101?enable

    Use PUT or POST or DELETE (for modify, add and delete respectively) 

  PUT /users/101/enable

2. Use nouns instead of verbs

    GET /getUsers

  GET /users

3. Keep singular and plural nouns separate

    For getting multiple resources, use only plural nouns

    GET /users

  GET /user   -> Can be used for single resource

4. Provide version for API

  /dce/api

  /dce/api/v1

    

5. Provide features : Select, Filter, Sort and Pagination

  GET /users?fields=name,class,balance

  GET /users?class=gold

  GET /users?sort=+class,-balance

  GET /users?limit=10&offset=20

6. Use resources hierarchy

  GET /users/101/cards

  GET /users/101/cards/citibank

7. Use HTTP status codes for errors

    Also provide error code with message description in JSON format.

    See HTTP error codes

8. Use HTTP headers for formats

    Specify format in HTTP header : 

• Content-Type for request format.
• Accept for list of allowed response formats.

Which HTTP error codes can be used by REST API ?

OK HTTP codes

200 = Success

201 = Success : New resource created

204 = Success : Resource deleted

KO HTTP codes

304 = Not Modified : Client uses cached data

400 = Bad request : Invalid request; Cannot be served; Details in the error payload like, JSON resposne

401 = Unauthorized : Request requires user authentication

403 = Forbidden : Access to requested resource is not permitted

404 = Not found : Resource not found for given URI

422 = Unprocessable : Server cannot process the entity

500 = Internal Server Error : Should not be thrown or returned from the API

What is WADL and how to generate them ?

WADL (Web Application Description Language) is an XML description of HTTP based web services.

We can assume it as equivalent to WSDL used in SOAP services.

Format of WADL

Resource is defined with its method (with request and response sub element) element.

param elements defines the inputs with name and type. 

Example

<application ...> 
   <resources base="URL"> 
     <resource path="search"> 
       <method name="GET" id="search"> 
         <request> 
           <param name="id" type="xsd:string" 
             style="query" required="true"/> 
           <param name="start" style="query" type="xsd:int" default="1"/> 
           <param name="sort" style="query" default="name"> 
             <option value="name"/> 
             <option value="city"/> 
           </param> 
           <param name="language" style="query" type="xsd:string" />
         </request>

 
         <response status="200"> 
           <representation mediaType="application/xml" 
             element="shaanns:ResultSet"/> 
         </response> 

         <response status="400"> 
           <representation mediaType="application/xml" 
             element="shaanns:Error"/> 
         </response> 
       </method> 
     </resource> 
   </resources>
 </application>

How to generate WADL or code from WADL ?

In Java, You can use Apache CXF or JAX-RS implementation like, Jersey.

Generate Java code using wadl2java 

wadl2java -o outputDir -p package [-a] [-s jaxrs20] [-c customization]* file.wadl

Example 

wadl2java -o out -p com.shaan.service myservice.wadl

Generate WADL using Jersey

https://github.com/jersey/jersey-1.x/tree/master/samples/generate-wadl

Generate WADL using Spring REST

http://javattitude.com/2014/05/26/wadl-generator-for-spring-rest/

Which HTTP method is used by the client to check what server receives when request is made ?

TRACE method

What could be the reasons to use RESTful Web service ?

Encouragements to use REST services

• Simple to implement and test
• supports various data formats such as XML, JSON etc.

SOAP vs. REST

SOAP vs. REST

• SOAP uses WSDL interface (contract) definition but REST not.
• REST is used over HTTP only but SOAP can be over any transport protocols such HTTP, FTP, STMP, JMS etc. 
• REST permits many different data formats where as SOAP permits only XML.
• SOAP uses SOAP envelope, but REST uses just messages.
• REST has better performance and scalability.