Building an API with Rails Panel - http://en.oreilly.com/rails2010/public/schedule/detail/14502 Panelists: Joe Ferris (thoughtbot, inc), Jeremy Kemper (37signals), Marcel Molina (Twitter), Rick Olson (GitHub), Derek Willis (The New York Times) Authentication
- OAuth 1.0 spec is difficult to implement - signature difficulties, etc
- OAuth 2 uses ssl & tokens - much simpler to implement, has overhead of SSL
Input & Response Formats
- Hoptoad now only supports XML - because they are write heavy and use streaming they were able to simplify their interface and make it faster by dropping support for other formats
- NYTimes - XML & JSON, expanded formats based on user needs
- Twitter - XML, JSON, RSS, Atom - probably going to move towards JSON only to scale up - XML is too verbose - lots of memcache full of XML fragments
- 37signals - uses RJS
To Version or Not to Version
- Twitter - hard problem - fork with multiple deploys? Inheritance? - lots of work. What do we need versioning for? Lotsa stuff we thought needed versioning actually didn’t. Looking for tips on how to do easily.
- 37signals - is it really a problem? If you think it needs a new versions, just make it a new resource
- How do you support legacy - 37signals: Given enough lead time application developers can deal with it fairly quickly (1 month).
- Hoptoad - no matter how many people you tell, they won’t upgrade. You won’t loose as may people as you think. People don’t upgrade until something is broken.
- Twitter - explosion of resources could be a problem. Implement new option/param/header to allow people to get new functionality during transition period. Look at analytics & how much time has passed then take out conditional and drop previous. “It’s going to break if you don’t upgrade.”
- NYTimes - “we’re shutting this off in 3 months”
Scaling
- NYTimes uses mashery and varnish
- 37signals - reverse proxy caching, usage patterns of API are usually very different than patterns of web traffic
- Twitter - cache not only fragments, but fragments of fragments - so that the more volatile stuff can expire without losing the more static data. Consider a streaming API instead of having users continuously poll. (mentioned “Cache Money” which I had to google cuz it’s a sweet name: http://github.com/nkallen/cache-money/tree/master)
- Github - take advantage of HTTP headers & caching
Code Separation
- Should there be a separation between your web & api code?
- Github - API code was in same code as controllers - became separate API controller - looking at moving to a Sinatra app
- Twitter - used to be DRY and works great for most applications. web/mobile/api encapsulated in respond to’s. Different code for rate limits, etc, “became unruly”, merge conflicts when split across teams, etc. Now they duplicate, but it’s not that bad because of skinny controllers & fat models.
- 37signals - just because twitter does it, doesn’t mean you have to. Much much easier to keep API in same code, should be exception to separate - this is why respond_to exists.
Security Concerns
- Twitter - “You’re going to get screwed no matter how awesome you are. And it’s a really hard problem.”
- Github: Don’t use cookies & sessions in your API requests
- 37signals - don’t worry about authenticating (use oauth) worry about authorization
Developer Communications
- Twitter - Tools & documentation - Page for “Is there a problem with the system?” - portal for developers
- Hoptoad - make sure your documentation is correct & up to date!
- 37signals - Don’t just put up a mailing list.
- NYTimes - use your own API - build samples & actually use/run them
- Github - documentation is actually stored in git
- 37signals - dogfooding