API design and documentation

api-design-and-documentation.md

Documented APIs:

• Github
• Twitter
• Facebook Graph API
• Stripe
• Instagram
• Strava
• RunKepper
• Feedly
• Mashery
• Foursquare
• RottenTomatoes
• Twilio
• Sales Force Desk

Design:

• Geert Jansen
• Best Practices for Designing a Pragmatic RESTful API
• interagent/http-api-design

Versioning:

4 main options:

• URL
• Accept Header
• Custom Header
• Query String

Thoughts on versioning:

Mark Nottingham - Chair of the Hypertext Transfer Protocol Bis Working Group HTTPbis WG. Mark has many thoughts on the subject, some of them listed below:

• Web API Versioning Smackdown
• Bad HTTP API Smells: Version Headers
• Evolving HTTP APIs

Proponents of URLs

• Vinay Sahni

Proponents of Accept Header:

• Pivotal Labs
• Steve Klabnik - Nobody understands REST or HTTP
• apigee
• Peter Williams

Haters of Custom Header:

• Mark Nottingham

No particular opinion:

• Troy Hunt's - Your API Versioning is wrong
• Web API Versioning options

What do organisations do:

Organisation	Versioning Method
GitHub	Accept
Twitter	URL
Facebook	URL
Stripe	URL & Custom
Instagram	URL
Runkeeper	Accept
Feedly	URL
Foursquare	URL & Query String
RottenTomatoes	URL
Strava	URL

Lexical Scope's view of the world here.

Summary:

Some considerations:

• Can a JS client send the accept header in all browsers? Test this JSFiddle
• Will proxies and other places where caching takes place cause problems if the headers are used to version?

Accept Header:

• [+] Widely accepted this is a sound use case for the header
• [-] Need to send back Vary header with Accept listed in order to ensure caches work

Custom Header:

• [-] Potential conflict with other header
• [-] Less support than using a standard Accept Header / not seen to be the way to do it

URL:

• [+] Is a good way to version big changes
• [+] It is really easy to see what version is being requested
• [+] It is the most common, widely used mechanism
• [+] A web browser can be used to change version being requested
• [+] No worries about clients not being able to handle setting headers or caches becoming stale because they ignore headers

Closing thoughts:

It breaks down to 2 types of changes:

1. Changes to the representation of the stuff (new properties added, old ones taken away).
2. Changes to the resources of the stuff (new methods, options like query string params).

Using the URL to do versioning is an additional pressure on what URLs are already used to do. i.e. identify resources, provide links to other resource, be cache keys.

Overall...

• Think about the future
• Do not, unless absolutely neccessary, break stuff
• Make everything backwards compatible
• Aim to get things as correct as possible, from the earliest possible point
• Think about what is being versioned - is it the resource or the representation?

Additional information:

http://www.digitalgov.gov/category/code/