Last Saturday was RedDotRubyConf 2012 in Singapore. Darcy Laycock (@sutto) gave a very nice talk about API driven development and was kind enough to pay us a visit at Viki and talk a bit more about his experiences. Here are some notes of the conference talk and the discussions with us.

Speed

• The expected response time for an API should be lower than 100ms. If it takes longer than that, you should probably worry.
• Caveat: search APIs can take longer, so no worries, that is expected
• See: this presentation by Instagram on how to work around slow parts of API
• Darcy and his team have found 50ms to be the sweet spot

Documentation

• The best API documentation is handwritten (i.e.: not auto-generated from code). Be sure to present your documentation in an easily navigable format.
• Consider including a console to explore the API. Consider using or following the example of Apigee.
• Like Echonest, provide a test auth key that developers can use to test with, but with low limits.
• Stripe, Twitter and Github APIs generally good examples to follow.

Internal protection

• For protection of internal APIs from outsiders, you could use an API key approach.
• However, Darcy’s team have found AWS firewalls to be a good alternative: they only allow internal apps to access their API endpoints.
• This approach is simple, and  has the same results as the key approach, for less complexity.

API architecture design

• One approach is to separate out APIs – e.g. have the Graph resource separate from the People resource, and combine those resources at another API service in front.
• Benefits of this approach: it’s easier to understand, and easier to test. Also, if you want to change the implementation of an API resource, for instance: switch the graph resource to a graph database, you can do that and know the API will continue to work.
• If speed is an issue here, use HTTP caching in front of each resource, because most of the time will be spent on IO-blocking operations.
• Also use threading at the combination stage, by requesting multiple resources at the same time. This is beneficial even with Ruby’s Global Interpreter Lock. And use Fibers in Ruby 1.9. There may still be some logic problems, but this is worth the speed benefit from taking a concurrent approach.

Design of APIs

• On API design, it does appear that Foursquare does something that Darcy has not seen in any other API: they display compact and full representations of objects. ‘Compact’ is the bare minimum to show in a list, e.g. a list of users; and a ‘full’ object is, say, a full profile of user.
• Each object returns a flag saying compact or full.

Hypermedia APIs

• ‘Hypermedia is the term people use to describe Roy Fielding’s original REST thesis. Rails doesn’t actually implement real REST.
• A distinctive feature of a Hypermedia API is that it is self-describing, parts links to other parts from within the API responses, just like on the web.

Security

• iOS-only apps can choose to not implement OAuth.
• In general, Darcy recommends OAuth, and 2.0 over 1.0. Because the standard will cover all use cases.
• OAuth 2 has something called ‘bearer’ tokens, that can be used for 2-legged authentication. This approach skips the typical OAuth dance.

Caching

• Use rack-middle in front of rack-cache to validate access token.
• Make access token part of the cache-key.
• Also you may use rack-middleware to set arbitrary HTTP “vary” header to cache based on other keys (e.g. country of the request)

Thanks to our fantastic intern Cedric (@ejames_c) for helping out taking notes.

By the way, we are currently growing our engineering team, check our current openings and write us to jobs@viki.com if you are interested in joining the Viki team!