Designing RESTful API's

From DevSummit
Jump to: navigation, search

Facilitated by Evan Henshaw-Plath,

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


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


  • 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


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


  • 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:
  • 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 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


  • 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