Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Best Practice in API Design

Best Practice in API Design

A series of tips and advice for making design decisions about building your API. Includes advice on caching, authorisation, other HTTP features, and more general elements such as error handling and usability.

D33d8bdd9096c80b8d1acca8d28410b5?s=128

Lorna Mitchell

November 09, 2013
Tweet

Transcript

  1. Best Practice in API Design Lorna Mitchell, CodeConnexx 2013

  2. About Me • Lorna Mitchell • http://lornajane.net • Developer/Consultant •

    I like to help with interesting projects
  3. Target Audience

  4. REST or RPC?

  5. REST REpresentational State Transfer • Uses URLs to idenfity resources

    • HTTP verbs indicate the action to perform Great for data-related systems
  6. REST Example What do you think you can find here?

    http://api.joind.in/v2.1/events/1394/talks
  7. REST Example • GET http://api.joind.in/v2.1/talks/9607 • • POST http://api.joind.in/v2.1/events/1394/talks •

    • PUT http://api.joind.in/v2.1/talks/9607 • • DELETE http://api.joind.in/v2.1/talks/9607
  8. RPC Remote Procedure Call • Call a function, pass parameters

    • Get a return value Ideal for existing libraries or function-related APIs
  9. RPC Example GET http://api.flickr.com/services/rest/ ?method=flickr.test.echo&api_key=b9a8a1bb1a09ca606d &format=rest <?xml version="1.0" encoding="utf-8" ?>

    <rsp stat="ok"> <method>flickr.test.echo</method> <api_key>b9a8a1bb1a09ca606dedcc95b07128bb1</api_key> <format>rest</format> </rsp>
  10. Data Formats

  11. JSON JavaScript Object Notation • Lightweight • Standard in most

    web languages • No data type information
  12. JSON Example { "event_uri": "http://api.joind.in/v2.1/events/1394", "speakers": [{ "speaker_name": "Lorna Mitchell"

    }], "start_date": "2013-11-08T09:30:00+01:00", "talk_description": "Give a man a fish and ...", "talk_title": "Opening keynote: Teach a Man to Fish", "comments_uri": "http://api.joind.in/v2.1/talks/9607/comments", "uri": "http://api.joind.in/v2.1/talks/9607", "verbose_uri": "http://api.joind.in/v2.1/talks/9607?verbose=yes", "website_uri": "http://joind.in/talk/view/9607" }
  13. XML eXtensible Markup Format • Verbose and descriptive • Includes

    data type information • Powerful/complicated
  14. Content Negotiation When the client says what formats it can

    handle, and the server works out what is best. Example header: Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 Format Weighting text/html 100% application/xhtml+xml 100% application/xml 90% */* 80%
  15. Content Negotiation $ curl -v -H "Accept: text/html" http://api.joind.in/v2.1/talks/9607 >

    GET /v2.1/talks/9607 HTTP/1.1 > User-Agent: curl/7.29.0 > Host: api.joind.in > Accept: text/html > < HTTP/1.1 200 OK < Date: Thu, 31 Oct 2013 22:25:37 GMT < Server: Apache < X-Powered-By: PHP/5.3.3-7+squeeze14 < Content-Length: 2845 < Content-Type: text/html; charset=utf8 < <!DOCTYPE html> ...
  16. Content Negotiation $ curl -v -H "Accept: application/json" http://api.joind.in/v2.1/talks/96 >

    GET /v2.1/talks/9607 HTTP/1.1 > User-Agent: curl/7.29.0 > Host: api.joind.in > Accept: application/json > < HTTP/1.1 200 OK < Date: Fri, 01 Nov 2013 09:16:46 GMT < Server: Apache < X-Powered-By: PHP/5.3.3-7+squeeze14 < Content-Length: 1395 < Content-Type: application/json; charset=utf8 < {"talks":[{"talk_title":"Opening keynote: Teach a Man to Fish" ...
  17. Choosing A Data Format • Who will use this service?

    • What will they do with it? • What's their technology platform? Consider supporting multiple formats
  18. Status Codes see also: http://flic.kr/s/aHsjxmmyGD

  19. Status Codes • Built in to HTTP • Give immediate

    feedback on success/failure • No need to parse response body
  20. Common Status Codes 200 OK 201 Created 204 No Content

    302 Found 304 Not Modified 400 Bad Request 404 Not Found
  21. Caching Headers

  22. Caching for a Finite Period Use the Expires header In

    the response: Expires: Thu, 21 Aug 2014 20:00:00 GMT
  23. Check for Newer Content Use Last-Modified In the response: Last-Modified:

    Thu, 31 Oct 2013 17:00:11 GMT In a later request: If-Modified-Since: Thu, 31 Oct 2013 17:00:11 GMT Response is either new content or has status 304 Not Modified
  24. Check for Newer Content Use ETag In the response: ETag:

    "8081-4ea0c61f81cc0;89-3f26bd17a2f00" In a later request: If-None-Match: "8081-4ea0c61f81cc0;89-3f26bd17a2f00" Response is either new content or has status 304 Not Modified
  25. Authorization Header

  26. Authorization Header Credentials are sent in the header • Simplest:

    Basic/Digest auth • Most flexible: OAuth2
  27. Heartbeat e.g. http://example.com/status

  28. Defaults

  29. Pick Your Defaults What is your user trying to achieve?

    • How many records? • How much detail? • Which default format?
  30. Error Handling

  31. Error Handling This is the true measure of your service

    • Errors must be in the expected data format • Appropriate status codes must accompany errors • Errors must be meaningful • Errors should be collated
  32. Consistency is Key

  33. Questions?

  34. Thanks! Feedback please! https://joind.in/9931