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. Best Practice in
    API Design
    Lorna Mitchell, CodeConnexx 2013

    View full-size slide

  2. About Me
    • Lorna Mitchell
    • http://lornajane.net
    • Developer/Consultant
    • I like to help with interesting projects

    View full-size slide

  3. Target Audience

    View full-size slide

  4. REST or RPC?

    View full-size slide

  5. REST
    REpresentational State Transfer
    • Uses URLs to idenfity resources
    • HTTP verbs indicate the action to perform
    Great for data-related systems

    View full-size slide

  6. REST Example
    What do you think you can find here?
    http://api.joind.in/v2.1/events/1394/talks

    View full-size slide

  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

    View full-size slide

  8. RPC
    Remote Procedure Call
    • Call a function, pass parameters
    • Get a return value
    Ideal for existing libraries or function-related APIs

    View full-size slide

  9. RPC Example
    GET http://api.flickr.com/services/rest/
    ?method=flickr.test.echo&api_key=b9a8a1bb1a09ca606d
    &format=rest


    flickr.test.echo
    b9a8a1bb1a09ca606dedcc95b07128bb1
    rest

    View full-size slide

  10. Data Formats

    View full-size slide

  11. JSON
    JavaScript Object Notation
    • Lightweight
    • Standard in most web languages
    • No data type information

    View full-size slide

  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"
    }

    View full-size slide

  13. XML
    eXtensible Markup Format
    • Verbose and descriptive
    • Includes data type information
    • Powerful/complicated

    View full-size slide

  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%

    View full-size slide

  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
    <
    ...

    View full-size slide

  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" ...

    View full-size slide

  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

    View full-size slide

  18. Status Codes
    see also: http://flic.kr/s/aHsjxmmyGD

    View full-size slide

  19. Status Codes
    • Built in to HTTP
    • Give immediate feedback on success/failure
    • No need to parse response body

    View full-size slide

  20. Common Status Codes
    200 OK
    201 Created
    204 No Content
    302 Found
    304 Not Modified
    400 Bad Request
    404 Not Found

    View full-size slide

  21. Caching Headers

    View full-size slide

  22. Caching for a Finite Period
    Use the Expires header
    In the response:
    Expires: Thu, 21 Aug 2014 20:00:00 GMT

    View full-size slide

  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

    View full-size slide

  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

    View full-size slide

  25. Authorization Header

    View full-size slide

  26. Authorization Header
    Credentials are sent in the header
    • Simplest: Basic/Digest auth
    • Most flexible: OAuth2

    View full-size slide

  27. Heartbeat
    e.g. http://example.com/status

    View full-size slide

  28. Pick Your Defaults
    What is your user trying to achieve?
    • How many records?
    • How much detail?
    • Which default format?

    View full-size slide

  29. Error Handling

    View full-size slide

  30. 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

    View full-size slide

  31. Consistency is Key

    View full-size slide

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

    View full-size slide