Kirsten Jones, Technical Leader, Cisco Systems                                          @synedra                          ...
   API Developers     Application Developers     Architects / Designers   Focus: Successful Developers
   Good Documentation   Common Pain Points   HTTP Sniffing   Understanding Error Codes   Debugging Strategies
   What can I do?   Walk-throughs and tutorials   Lots of working code   Small chunks with frequent successes   Examp...
   Lack of understanding of HTTP structure   Libraries “masking” responses   Error code confusion   Authentication
   Many developers don’t understand HTTP    basics   Libraries allow them to interact with the API    but not understand...
   Clear and complete tutorials, with and    without libraries   Pointers to HTTP basics     My OSCON presentation has ...
 3rd Party (or company-supported) libraries are    great but…   Frequently error codes or other responses are    masked...
   HTTP status is very helpful       50x: we screwed up.       40x: you screwed up.       30x: ask that dude over ther...
   Teach your developers to be successful   Watch the traffic with a sniffer   All requests should include headers, bod...
   Use existing, tested libraries   Code defensively   Servers aren’t that smart     In most cases a working example w...
   Macintosh: HTTPScoop    http://tuffcode.com/   Macintosh: Charles (supports SSL)    http://www.charlesproxy.com/   W...
   401 authentication errors (signatures, tokens)   403 authorization errors (throttles,    permissions)   400 errors –...
   Pain points   HTTP Sniffers   Good questions
Upcoming SlideShare
Loading in …5
×

Successful developers

1,028 views

Published on

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

Published in: Technology
0 Comments
4 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,028
On SlideShare
0
From Embeds
0
Number of Embeds
55
Actions
Shares
0
Downloads
15
Comments
0
Likes
4
Embeds 0
No embeds

No notes for slide
  • How do they differ?Sometimes they can be used interchangeably – we’ll see an example of this later with OAuth – then the developer can chooseUsually parameters are used to refine the request, better define what’s being requested, and headers are used for metadataFormat or metadata about the request
  • Secure/not securePretty/not prettyWireshark is nice but ugly (X11)
  • Successful developers

    1. 1. Kirsten Jones, Technical Leader, Cisco Systems @synedra http://www.princesspolymath.com
    2. 2.  API Developers  Application Developers  Architects / Designers Focus: Successful Developers
    3. 3.  Good Documentation Common Pain Points HTTP Sniffing Understanding Error Codes Debugging Strategies
    4. 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. 5.  Lack of understanding of HTTP structure Libraries “masking” responses Error code confusion Authentication
    6. 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. 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. 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. 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. 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. 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. 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. 13.  401 authentication errors (signatures, tokens) 403 authorization errors (throttles, permissions) 400 errors – parameters, headers Content-type errors
    14. 14.  Pain points HTTP Sniffers Good questions

    ×