How to support the developers of your API, give them skills and tools to be successful. Webex of my presentation at https://cisco.webex.com/ciscosales/lsr.php?AT=pb&SP=MC&rID=62417452&rKey=caa6309156837b7a

1. Kirsten Jones, Technical Leader, Cisco Systems
@synedra
http://www.princesspolymath.com

2.  API Developers
 Application Developers
 Architects / Designers
 Focus: Successful Developers

3.  Good Documentation
 Common Pain Points
 HTTP Sniffing
 Understanding Error Codes
 Debugging Strategies

4.  What can I do?
 Walk-throughs and tutorials
 Lots of working code
 Small chunks with frequent successes
 Example applications
 Examples:
 LinkedIn Javascript Tutorials
 LinkedIn Getting Started

5.  Lack of understanding of HTTP structure
 Libraries “masking” responses
 Error code confusion
 Authentication

6.  Many developers don’t understand HTTP
basics
 Libraries allow them to interact with the API
but not understand issues
 REST feels like a “black box”

7.  Clear and complete tutorials, with and
without libraries
 Pointers to HTTP basics
 My OSCON presentation has good info
 Developer tools demonstrating successful
calls (OAuth Test Console, IODocs)

8.  3rd Party (or company-supported) libraries are
great but…
 Frequently error codes or other responses are
masked
 Can get out of sync
 Supporting the API is different from
supporting a library

9.  HTTP status is very helpful
 50x: we screwed up.
 40x: you screwed up.
 30x: ask that dude over there.
 20x: cool.
 Consistency within the API is critical
 Useful error messages for broad errors (4xx
errors)
Document, explain, demonstrate!

10.  Teach your developers to be successful
 Watch the traffic with a sniffer
 All requests should include headers, body,
exact URL
 A great bug report:
 I did X
 I expected Y to happen
 To my dismay, Z happened instead

11.  Use existing, tested libraries
 Code defensively
 Servers aren’t that smart
 In most cases a working example will help
 Lots of code samples, well documented
 Use case based

12.  Macintosh: HTTPScoop
http://tuffcode.com/
 Macintosh: Charles (supports SSL)
http://www.charlesproxy.com/
 Windows: Fiddler
http://www.fiddler2.com/fiddler2/
 Unix (or Mac): Wireshark (X11)
http://www.wireshark.org/

13.  401 authentication errors (signatures, tokens)
 403 authorization errors (throttles,
permissions)
 400 errors – parameters, headers
 Content-type errors

14.  Pain points
 HTTP Sniffers
 Good questions