Best Practice in API Design

Best Practice in API Design Lorna Mitchell, CodeConnexx 2013

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

Target Audience

REST or RPC?

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

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

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

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

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>

Data Formats

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

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

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

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%

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

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

Choosing A Data Format • Who will use this service?
• What will they do with it? • What's their technology platform? Consider supporting multiple formats

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

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

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

Caching Headers

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

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

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

Authorization Header

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

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

Defaults

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

Error Handling

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

Consistency is Key

Questions?

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

Best Practice in API Design

Best Practice in API Design

More Decks by Lorna Mitchell

Other Decks in Programming

Featured

Transcript