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.

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