From http://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf
Routes
- 2 base urls per resource ("/dogs" and "/dogs/1234")
- Keep verbs out of base URLs -HTTP verbs to operate on collections and elements -Shouldn't need URL deeper than /resource/identifier/resource -Sweep parameters under HTTP ? ("GET /dogs?color=red&state=running&location=park")
Errors
Start with 3 error codes: 200, 400 - Bad Request, 500 - Internal Server Error
Example error message:
200 - OK 400 - Bad Request
{"developerMessage" : "Verbose, plain language description of the problem for the app developer with hints about how to fix it.", "userMessage":"Pass this message on to the app user if needed.", "errorCode" : 12345, "more info": "http://dev.teachdogrest.com/errors/12345"} <- Add a link to more information
Pagination and partial response
Google's partial response: "/dogs?fields=name,color,location"
Pagination: "/dogs?limit=25&offset=50
Supporting multiple formats: "dogs.json" or "dogs.xml"
Consider naming attributes in a JS-friendly manner. E.g. instead of "created_at", "createdAt" so that time = myObject.createdAt
Search
Global search (/search?q=fluffy+fur)
Scoped search (/owners/5678/dogs?q=fluffy+fur)
Formatted results (/search.xml?q=fluffy+fur)
API subdomain
api.socrates.com developer portal: developers.socrates.com (where devs go)