REST API Best Practices

Base Url's
Only 2 base urls 1) collection & 2) singular
/dogs
/dog/ig

Use nouns & not verbs
/deals  - Groupon
/checkins - Foursquare

// do not have getDogs / getDogById
use HTTP Methods GET, POST, PUT, DELETE to define CRUD operations

How to handle associations
Get all dogs belonging to a owner 5678
eg: GET /owners/5678/dogs

Create a new new dog for a specific owner
eg: POST /owners/5678/dogs

Additional / optional parameters
GET /owners/5678/dogs?color=red&type=pet

Errors

1. code : use HTTP status codes
2. message : have message
3. more_info : have url for error docs; get more context; get help

Versioning

• have version at the start, do not have it in the middle 
• have highest level scope as much to the left as possible

eg:
/v1.2/dog/5678
Note: Do not release an API without versioning
why? FB moved from v1.2 to v1.3 and all apps supporting v1.2 broke

Partial Response

• If you only want some fields out of the whole data - want only id, name, type from an entire list of data

eg:
LinkedIn -> /people:(id,first-name,last-name,industry)
Facebook -> /saumilps/friends?fields=id,name,picture

Pagination

• have an offset & limit

eg:
/dogs?limit=25&offset=50

Formats
Spit more than one format

• /dogs.json
• /dog/1234.json
• Accept: application/json (pure RESTful way / in the header)
• ?type=json

Authentication
OAuth