Use 2 base URL's per resource, one for collection and one for specific element
For collection
/dogs -- get list of all dogs
For specific element
/dogs/12345 -- get details of dog 12345
Map HTTP methods to CRUD methods uniformly.
+-------------+-------------+
| HTTP Method | CRUD Method |
+-------------+-------------+
| GET | Read |
| POST | Create |
| PUT | Update |
| DELETE | Delete |
+-------------+-------------+
** Exception to Best Practice: Prefer ReadAll for GET requests on collection
Resource mapping from wikipedia, modified to be more pragmatic.
+-------------+----------+---------------+---------------------+------------------+
| Resource | POST | GET | PUT | DELETE |
+-------------+----------+---------------+---------------------+------------------+
| /dogs | create a | list all dogs | bulk update dogs | delete all dogs |
| | new dog | | | |
| /dogs/12345 | error | details for | if exists, | delete dog 12345 |
| | | dog 12345 | update dog 12345 | |
| | | | If not, | |
| | | | error | |
+-------------+----------+---------------+---------------------+------------------+
Use plural verbs vs singular. For example, /dogs vs /dog
For example, /dogs vs /animals ( depends on business use case )
Example:
+------+---------------------+-----------------------------+
| GET | /owners/obama/dogs | get all dogs owned by Obama |
+------+---------------------+-----------------------------+
| POST | /oweners/obama/dogs | add a dogs owned by Obama |
+------+---------------------+-----------------------------+
Example:
/dogs?color=red&state=running&location=park -- get all red dogs running in the park
Use HTTP status codes as much as possible - http://en.wikipedia.org/wiki/List_of_HTTP_status_codes
200 - OK
401 - Unauthorized
Response body should give more information about error
Example:
{
"message" : "verbose, plain language description of problem with hints on how to fix it",
"more_info" : "http://dev.<topdomain>.com/errors/12345"
}
Never release an API without version number.
Use Simple version numbers in URL - as left as possible.
Example: /v1/dogs
Use fields as optional query param with comma separated attribute names.
Example:
/dogs?fields=name,color,location
For sub-objects, provide a way to select fields.
Example:
/dogs?fields=name.color,location(city)
Use offset and limits
Example:
/dogs?limit=25&offset=50
Default to limit = 10 and offset = 0 -- depends on data size
Use . URL extension
Example:
/dogs.json -- list all dogs in json format
/dogs/12345.json -- details of specific dog in json format
Use camelCase attribute names
verbs like calculate, tranlate, convert - represents more of operation than object
Example:
/convert?from=EUR&to=CNY&amount=100
Global Searches
/search?q=fluffy+fur
Scoped Searches
/oweners/obama/dogs/search?q=fluffy+fur
/dogs/count -- number of resources in database
api.<topdomain>.com for api requests
dev.<tomdomain>.com for dev conncections/documentations
perform web redirects from api -> dev
Specify query parameter to supress HTTP status codes
Example:
/dogs?supress_response_codes=true
This should returns HTTP 200 for all HTTP request.
If implemented, http response body should have the response code
Example:
{
"response_code" : "401",
"message" : "verbose, plain language description of problem with hints on how to fix it",
"more_info" : "http://dev.<topdomain>.com/errors/12345"
}
Add method parameter in URL
Example:
/dogs?method=post -- create a new dog
/dogs -- get all dogs
/dogs/1234?method=put&location=park -- update dog 1234
/dogs/1234?method=delete -- delete dog 1234
Use OAuth 2.0
Divide application in 3 layers:
+-----------------------------+
| Application |
+-----------------------------+
+-----------------------------+
| API Virtualization Layer |
+-----------------------------+
+-----+ +-----+ +-----+
| API | | API | | API |
+-----+ +-----+ +-----+