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.

Transcript

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

   View Slide

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

   View Slide

3. Target Audience
   

   View Slide

4. REST or RPC?
   

   View Slide

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

   View Slide

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

   View 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 Slide

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

   View 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 Slide

10. Data Formats
    

    View Slide

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

    View 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 Slide

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

    View 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 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 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 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 Slide

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

    View Slide

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

    View Slide

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

    View Slide

21. Caching Headers
    

    View Slide

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

    View 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 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 Slide

25. Authorization Header
    

    View Slide

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

    View Slide

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

    View Slide

28. Defaults
    

    View Slide

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

    View Slide

30. Error Handling
    

    View Slide

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
    

    View Slide

32. Consistency is Key
    

    View Slide

33. Questions?
    

    View Slide

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

    View Slide