REST Developer Success

Kirsten Jones, Technical Leader, Cisco Systems

@synedrahttp://www.princesspolymath.com

Who’s this talk for?

API Developers Application Developers Architects / Designers

Focus: Successful Developers

What do developers need?

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

Better Documentation

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

Common REST Pain Points

Lack of understanding of HTTP structure

Libraries “masking” responses Error code confusion Authentication

Understanding HTTP

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”

Facilitating HTTP Understanding

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)

3rd Party Libraries

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

Error codes

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!

Helping Developers Debug

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

Preventing preventable issues

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

HTTP Sniffers

Macintosh: HTTPScoophttp://tuffcode.com/

Macintosh: Charles (supports SSL) http://www.charlesproxy.com/

Windows: Fiddlerhttp://www.fiddler2.com/fiddler2/

Unix (or Mac): Wireshark (X11)http://www.wireshark.org/

Common Issues

401 authentication errors (signatures, tokens)

403 authorization errors (throttles, permissions)

400 errors – parameters, headers Content-type errors

Questions?

Pain points HTTP Sniffers Good questions