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.

Lorna Mitchell

November 09, 2013
Tweet

More Decks by Lorna Mitchell

Other Decks in Programming

Transcript

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

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

    http://api.joind.in/v2.1/events/1394/talks
  3. 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
  4. RPC Remote Procedure Call • Call a function, pass parameters

    • Get a return value Ideal for existing libraries or function-related APIs
  5. 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>
  6. 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" }
  7. XML eXtensible Markup Format • Verbose and descriptive • Includes

    data type information • Powerful/complicated
  8. 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%
  9. 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> ...
  10. 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" ...
  11. Choosing A Data Format • Who will use this service?

    • What will they do with it? • What's their technology platform? Consider supporting multiple formats
  12. Status Codes • Built in to HTTP • Give immediate

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

    302 Found 304 Not Modified 400 Bad Request 404 Not Found
  14. Caching for a Finite Period Use the Expires header In

    the response: Expires: Thu, 21 Aug 2014 20:00:00 GMT
  15. 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
  16. 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
  17. Authorization Header Credentials are sent in the header • Simplest:

    Basic/Digest auth • Most flexible: OAuth2
  18. Pick Your Defaults What is your user trying to achieve?

    • How many records? • How much detail? • Which default format?
  19. 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