Best Practice in API Design

Slide 1

Slide 1 text

Best Practice in API Design Lorna Mitchell, CodeConnexx 2013

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

Target Audience

Slide 4

Slide 4 text

REST or RPC?

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

Data Formats

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

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%

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

Caching Headers

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

Authorization Header

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

Defaults

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

Error Handling

Slide 31

Slide 31 text

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