API design best practices

API Design summary

1. Use two base URLs per resource
2. Keep verbs out of your base URLs
3. Use HTTP verbs to operate on the collections and elements

4. Be consistent either use plural nouns or singular nouns

5. Use concreate names rather than abstract names

    An intuitive API uses plural rather than singular nouns, and concrete rather than abstract names

6. keep your API intuitive by simplifying the associations between resources, and sweeping parameters and other complexities under the rug of the HTTP question mark.

Handling errors

• Errors boil down to

• Everything worked - ok

• The application did something wrong – client error

• The API did something wrong – server error

In summary, be verbose and use plain language descriptions. Add as many hints as your
API team can think of about what's causing an error.

eg: HTTP Status Code: 401
{"status" : "401", "message":"Authenticate","code": 20003, "more info": "http://www.twilio.com/docs/errors/20003"}

Google uses max error codes of 10 -
200 201 304 400 401 403 404 409 410 500

Tips for versioning

If it changes the logic you write to handle the response, put it in the URL so you can see it
easily.

If it doesn't change the logic for each response, like OAuth information, put it in the header.
Never release an API without a version. Make the version mandatory.
Specify the version with a 'v' prefix. Move it all the way to the left in the URL so that it has
the highest scope
Use a simple ordinal number. Don't use the dot notation like v1.2 because it implies a
granularity of versioning that doesn't work well with APIs--it's an interface not an
implementation. Stick with v1, v2, and so on.

Pagination and partial response

requesting for partial information and retrieving it
eg:  Facebook
      /joe.smith/friends?fields=id,name,picture
      Google
     ?fields=title,media:group(media:thumbnail)

The partial selection syntax can also be used to include associated resources cutting down
on the number of requests needed to get the required information.

paginate objects in a database

Use limit and offset
/dogs?limit=25&offset=50

Support partial response by adding optional fields in a comma delimited list.

Use limit and offset to make it easy for developers to paginate objects.

For Actions

Use verbs not nouns
For example, an API to convert 100 euros to Chinese Yen:
/convert?from=EUR&to=CNY&amount=100

Make it clear in your API documentation that these “non-resource” scenarios are
different.
Simply separate out a section of documentation that makes it clear that you use verbs in
cases like this – where some action is taken to generate or calculate the response, rather
than returning a resource directly

Attribute Names

Use JSON as default
• Follow JavaScript conventions for naming attributes
- Use medial capitalization (aka CamelCase)
- Use uppercase or lowercase depending on type of object

Search

Global search you can use /search?=afdfas+fsda search is a verb and ?q is the query
Scoped search /items/2324/slices?q=afd+dfa search term is dropped and we rely on the parameter as search indicator

Consolidate API request in one subdomain

its cleaner, easier and more intuiative for devs, Your API is on the top-levl domain, api.mydomain.com
developer portal will be developers.mydomain.com

Do web redirects

Exceptional Behaviors

Use suppress_response_codes = true
Return Ok Always
and Push any response code down to the response message

eg:
Always return OK
/items?suppress_response_codes = true
Code for ignoring
200 - OK
Message for people & code
{response_code" : 401, "message" : "Verbose, plain language
description of the problem with hints about how to fix it."
"more_info" : "http://dev.tecachdogrest.com/errors/12345",
"code" : 12345}

When clients support limited HTTP methods

To maintain the intergrity of the four HTTP methods make the method an optional parameter in the URL
Then the HTTP verb is always GET but you can express rich HTTP verbs and still maintain a RESTful clean API
but this is little dangerous since you allowing POST to be done using GET and Web crawlers like the Googlebot can create
or destroy lots of content inadvertently.

Authentication

Paypal - uses proprietary 3-legged permission API
Facebook - OAuth 2.0
Twitter - OAuth 1.0a

Recommendation - Use Auth 2.0 which will mean improved security and better end-user and consumer experiences with Web
and mobile apps. Don't use something *like* OAuth but different.

The API façade pattern

Implementing an API facade pattern involves 3 steps
1. Design the ideal API - design the URLs, request parameters and responses, payload, headers, query parameters etc.
2. Implement the design with data stubs. This allows devs to use the API with data before internal systems are connected.
3. Integrate between facade and the systems

	POST	GET	PUT	DELETE
resources	single add	List	update Bulk	delete
resources/1234	error	1234	update	delete

Reference

http://info.apigee.com/Portals/62317/docs/web%20api.pdf