Thursday, October 17, 2013

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.

Friday, October 11, 2013

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.