RESTful API Standards

Below are the common RESTful API standards that we should follow when designing our API's

Keep your base URL simple and intuitive

 /dogs     /dogs/1234

Keep verbs out of your base URLs

Never use /getDogs or /createDogs

Use HTTP verbs to operate on the collections and elements

POST, GET, PUT, DELETE is CRUD (Create-Read-Update-Delete)

Use Plural nouns

/dogs   /deals    /quotes

Concrete names are better than abstract

Instead of /items be more specific like /blogs  /videos

Number of resources - preferably between 12 to 24

Simplify the Relationship and Association between Resources

GET /owners/5678/dogs

POST /owners/5678/dogs

Keep complexity behind the ‘?’

GET /dogs?color=red&state=running&location=park

Have a good error design

                Aligning errors with HTTP status codes

                200 - OK

                400 - Bad Request from client

                500 - Internal Server Error

                304 - Not Modified

                404 – Not Found

                401 - Unauthorized

                403 - Forbidden

                Provide a more granular error message

                {"status" : "401", "message":"Authentication Required","code": 20003}

Versioning is mandatory

Always use v and never have minor version like v1.0. Ideal is v1, v2

Have version all the way to the left (highest scope): /v1/dogs

Maintain at least one version back

Follow proper cycle for deprecating and retiring the API

Response content type, OAuth etc must go into the header

information which doesn't change the logic for each response goes into the header

Extra optional fields must be requested in a comma-delimited list

/dogs?fields=name,color,location 

Pagination is a must for resource API's

Use limit and offset. 

/dogs?limit=25&offset=50

default pagination is limit=10 with offset=0

For Non-Resource API's: Use verbs not nouns

/convert?from=EUR&to=CNY&amount=100

/translate?from=EN&to=FR&text=Hello

Request format - support multiple if possible

Default should be JSON, but support XML if possible

Use the pure RESTful way with the header, Accept: application/json

Use standard Java/Javascript naming convention for attributes

example: createdAt, firstName

Search within a resource: use ?q=

/owners/5678/dogs?q=fluffy+fur

Have all API's in single store and under one domain

api.mycompany.com

Option to Supress error codes

Always sent HTTP 200, even in case of errors.

&suppress_response_codes=true

Authentication : Use OAuth 2.0

In addition to the atomic API, provide composite API's as well if required - if there is a need

This will avoid applications making multiple calls per screen.

Complement the API with code libraries and a software development kit (SDK)

Note: These are not the only standards and there may be variations. These are the standards which are followed my many and works for them.

Build and Deploy the PLAY application

Once you have developed a application in play, you might want to create a binary out of it which you can deploy on another server.
The below steps have to be followed to create a binary of your Play application and to deploy on another server (Linux).

1. In your play application directory, run the below command.
[My application folder] $ play dist
This command will create a zip file with the following name [applicationName]-[version].zip. Example: testapp-1.0.zip.
2. Copy this zip file to the server on which you want to deploy the application.
Example: scp testapp-1.0.zip user@other-server-host:/home/user/.
3. Unzip the file to the folder where you want the application running.
Example: unzip testapp-1.0.zip -d /opt
4. You will find a start file in the unziped folder. But most of the time it will not have executable permissions.
Change the permission by executing the below command.
chmod 777 start
5. You can then execute the command like below.
[Unzipped dist folder] $ ./start

You can also make your application run on different port and provide other options along with the ./start.
Refer the below URL for the options.
http://www.playframework.com/documentation/2.1.x/ProductionConfiguration

Hoping that this information helps some newbies of Play.

Sonar - Code Quality Management

This Sonar tool is saving me a lot of time these days. Gone are the days where I need to worry about the developer following the coding standards of JAVA, HTML and JS.
I only need to worry about the business logic review these days.

This open source tool is surely a must have for every team. Check it out.
http://www.sonarsource.com/

The developers are also benefited as they are able to improve in their coding standards by using this tool.

Few plugins which are impressive are
http://docs.codehaus.org/display/SONAR/Quality+Index+Plugin
http://docs.codehaus.org/display/SONAR/Toxicity+Chart+Plugin
http://docs.codehaus.org/display/SONAR/Motion+Chart+Plugin

There are lot more though which can be easily added.

Exception Handling - Non happy path

When a application or process is developed, the main requirement would be quite simple or might look simple. But have a look at the below diagram which shows a process which is part of an application (courtesy: workflowpatterns).



The solid lines (which are only 3) indicate the normal state through which the execution will flow. We could accomplish this normal flow with some programming knowledge and some technical skills.

But the tricky part is the flow indicated using dotted lines. There are 17 of them!
These will not be considered during most of the discussions with the business owner. Many of them might be even missed during design and implementation. But they are important for sure. These dotted flows make the application fail proof and allows the support team to maintain the application without nightmares.

If you think you can develop an application within a few days, then you are surely not considering these dotted lines, as this is the part which takes more time during the development and testing cycle.
If you don't want to get stuck with maintaining the application for long and don't want to have sleepless nights on production issues, then consider all possible dotted lines (in other words the Non-Happy paths) for your application. Also make sure you let your business owners know the importance of handling all exception scenarios. This might take a little longer for your application to go live, but it will stay live for longer.