Designing RESTful API's

Facilitated by Evan Henshaw-Plath, protest.net

Evan has designed more than his fair share of API's, and he will share his methodology and processes for RESTful API design, and discuss what distinguishes a good API from a poor one.

Designing RESTful API's/notes

Notes

raw notes

Why do a session?

• Folks sing SOAP <- not good
• People dont seem to know about REST APIs
• Began with PhD document

Why is SOAP bad (or different)?

• Simple Object Access Protocol
• Lots of API Protocols
• XMLRPC came out and was simple, then larger groups created SOAP
• RPC - Remote Procedure Call
  • Predates Internet. It's calling a method that is on a remote resource
• Offers list of discovery and schema

REST

• That each URL is a resource
• Each HTTP method is an action
• Can provide same URIs for web application via browser and via API
• Original Standard created by Roy Felding
  • Current implemtations are often mutations
• not language specific (only languages that can utilize HTTP)
• WADDLE ??
• Format agnostic
  • Return close to internal data format
  • Can return HTML, XML, JSON
    • .html, .json
    • MIME Types
• Ruby and Django are often better at RESTful APIs

HTTP Verb (Actions)

• Get - read
• Post - create (update)
• Put - update (create)
  • Not usually used
  • Like file upload
  • Have to know what the URL is, not good for auto-incrementing
• Delete - delete
  • Not usually used
  • Remove resource

CRUD

• create, read, update, delete
• The basic building blocks of web applications
• REST HTTP methods are same as CRUD

WSDL

• Offeres discovery of API
• Do we need it?
  • vs documentation
  • discovery does not actually offer ability to create application

Design API

• Write first
• Build a sample client
• FireEagle
  • release client implementation in many languages
• Determine what is returned
  • As much as possible that is easier for you as provider
  • Objects
    • Not usually worth filtering fields/parts of an object
    • Cache objects
  • Lists are different
    • Offset problems with updating and listing at the same
    • Pagination
      • Ability to paginate or not? Some instances do not let pages, or a limited amount of pages
      • Do not paginate if there is a JOIN in query
      • List of IDs (not the whole object), then get objects separate
    • Need to index database
      • Nothing in WHERE clause should not be indexed
      • Better to have many requests that are cacheable than fewer requests with lots of processing time
        • HTTP is faster than MySQL
      • Example: FriendFeed
        • Millions of requests a day
        • Could have done fewer requests with larger queries without index
• Conditional GET to determine if there is a change
  • Always provide Last MOdified in HTTP Headers
  • eTag -> MD5 hash of content
• Output Standards
  • If data can be in ATOM, do it so that the data is more distributable
  • iCal, not great standard, easy to implement
  • if can use easy, popular standards, good to use
• Frameworks often have REST implementations
• example exposue: example.org/api/v1/customer/1/find?blah=1
• By putting API in other folder, can filter and put that load on a different server
• How are building people building REST APIs???????? (public)
• What to use in Standard?
  • REST design that works like RPC
  • Use response formats
  • important to eTags and Last Modified
  • Put and Delete are not that useful
  • Get and Post are useful
• Good URI
  • is guessable
  • /api/categories/list/format
  • /api/categories/1/post/all/xml
  • NO definte right, but just by example that are being used

REST vs RPC

• REST has object and verb (in headers)
• RPC has verb with parameters

Upgrade APIs

• use version paths
• people dont upgrade
• never remove anything
  • or make sure that previous data is put to null
• mapping and translation from API to DB can be useful

Web Frameworks

• PHP -> Symfony, CakePHP, CodeIgnitor, Zend
• Ruby on Rails
• Django
• ORM
  • Object Relational Model
  • Translating data from DB to Object

JSON

• a lot of new REST APIs output JSON
• serialize JS objects
• Easily parsing

User Authentication

• Twitter
  • AuthBasic
  • Twitter apps need password
• Token based
  • Google offers APIs
  • offer tokens instead of username/password
  • Token in HTTP Headers, or URI parameter
• Consitent Way?
  • OAuth
  • originally developed for Twitter
  • Consitent set of libraries for multiple languages
  • Example
    • FireEagle
      • iPhone has permission to tell Facebook which asks FireEagle for a token on behalf

Front Caching

• ModProxy or Squid
• Problems arise with Authentication

Ruby on Rails

• 7 Holy verbs
• There are sometimes different actions that need to happen (ie Registration Status update)

Future of Web Standards

• Jabber (XMPP extensible messaging presence protocol) and REST
  • Sends XML
• Publish and Subscribe
• Problem: ask every 5 minutes to recieve NO for 5 months
• Use XMPP to use Signals instead of Pulls
• HTTP is more overhead compared to XMPP
  • HTTP(S) has only single connections each time
  • XMPP caches messages
• Web Server is repsonsible to tell about changes
• Web Hooks
  • Like TracBack
  • Good for few requests
  • Can't handle 20,000/min
• XMPP
  • Can handle 20,000/min
• Twitter
  • Offers ?? XMPP