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.

1 comment:

  1. I would never integrate version into the base uri, instead put it into header (Content type) or at the very least as request parameter.

    http://www.stackoverflow.com/questions/389169/best-practices-for-api-versioning/

    ReplyDelete