Field Notes Inside an Integrated Communications Agency

Web service APIs not only have to work, but they must also appeal to developers' high expectations. It's not enough to expose their data; if you don't offer powerful functionality, provide clean documentation, and maintain reliable service, they'll invest their time elsewhere. On this panel, developers from leading web applications share their best practices for building developer-friendly web service APIs.

Avi Bryant CEO , Dabble DB
Leah Culver Founder/Developer , Pownce
Carl Mercier CEO , defensio.com
Ari Steinberg Engineering Manager , Facebook
Ben Vinegar Web Dev , FreshBooks

h1. Building Developer-Friendly Web Service APIs

h2. Formats

* Request & Response
    * DabbleDB: CSV, JSONz
        * Meant for non developers

* Defensio: XML, YAML (Post)
    * Don't currently us JSON
    * Take a lot of care when developing

* Facebook: XML, FQL, JSON
    * A version of JSON is very easy to work with
    * Extremely popular

* Pownce: XML, JSON (REST)
    * Developed in Python
    * Developed Data Structure first, then the API

h3. Benefits

* Brings in Developers

* FQL
    * Request VS response model
    * Browered from SQL previously
    * Made it easier to update and more
    * 40% of their API calls

* People often build libraries on top

* Makes it quicker and easier

h2. Authentication

* DabbleDB: HTTP Basic Auth, URL token
* Defensio: URL token
* Facebook: OAuth-Style
* Pownce: HTTP Basic Auth, OAuth
* Really important to do properly
* Important to think about how they are used
    * Desktop Client
    * Web Client or Widget

* SSL is the best, but very slow
* Token based the best after SSL
* Authentication Method - Dependent on how important the DATA is

h2. Change

* Worst thing for 3rd party developers, makes it hard to progress
* Version API, one of the best ways
* If just adding fields not as big a deal, but overhauls make it a pain
* Being transparent is really important, and helps the 3rd party
* Be ready to support the API almost indefinitely, or deal with pissed off customers
* Also warn them ahead of time if you kill an API, give a couple warnings * When building a new version or piece to an API, start Documentation right away

h2. Performance

* Dependent on what you are requesting and types of Data to request
* it's something that depends on it usage, 3rd party developers should think about how its being used and requested during their dev
* Caching can be very helpful
* API service VS. Web Server request can be different
* Be ready for things to be hit in ebbs and flows
* Think about the tools and how they work (ie. Merb vs. Rails :Defensio)
* Monitor vs. Limit Requests if you start to become a large service
* Be willing to help 3rd party dev if you see they have inefficient processes, usually it gets cleared up pretty quickly

h2. Community

* One of the Most important things you can do
* Helps grow the services
* Staff your customer support
* have Customer Support and Developers work closely and communicate
* It becomes and Incentive to use your service/product
* Showcasing good 3rd party apps REALLY helps your service/product
* Helping debug their code when they are having massive problems helps make them love and spread the word about your service
* IRC channels are a great way to be there
* Hiring from this community can be a great way to help build your team

h2. Q&A

* Make the API easy to use
* Make sure its the right thing for the users VS. sticking hardcore to a standard
* Client Library developers can be helpful in understanding how its used
* You should be your own API user
* Build different levels of your API in you app so that you can use it and build you own app
* Emulating your competitors can really help you start out and build your business, just make sure it fits and makes sense
* Having a Developer Sandbox for an API can be helpful for your debugging and the 3rd party app users
* Biggest issue besides Scaling
    * Giving Incentives