api design

API Design

Who Am I?

Bournemouth Uni Graduate

Clock – Software Engineer

Synth Media – Technical Director

@synthmedia – Business

@domudall – Srs

@dmno – Not so srs

http://github.com/domudall Dom Udall

Apologies

Where I’ve Stolen This From

http://www.slideshare.net/MikePearce/api-anti-patterns-4920731https://vimeo.com/13922981

http://mikepearce.net/

REST

verb noun

GET/POST Tunnelling

• GET• POST• PUT• DELETE• HEAD

• TRACE• OPTIONS• CONNECT• PATCH

http://en.wikipedia.org/wiki/HTTP_method#Request_methods

PUT or POST

“The client uses PUT when it’s in charge of deciding which new URI the resource should have. The client uses POST when the server is in charge…”

O’Reillys RESTful web services

Responsible Responses

• Send the correct content type header

• Don’t send mixed responses

• Use the correct response code!

Response Codes

• 1xx – Informational

• 2xx – Successful• 3xx – Redirection• 4xx – Client Error• 5xx – Server Error

http://en.wikipedia.org/wiki/List_of_HTTP_status_codes

Caching

• Between application and database

• In the application itself• Using an API proxy• CDN for large static content

Cookies

• NO!• REST is meant to be

stateless• One change to token

handling can render all tokens useless

HATEOAS

Hypermedia as the engine of application state

Huh?

HATEOAS

• Clients shouldn’t be building URIs

• API responses return end points

• API end points can change without disruption to the client

GET: http://api.startup.co/users

Versioning

• Grey area• Goes against HATEOAS• Can either:– Versioning all URIs– Not versioning main URI– Not versioning at all

Document Extensions

• Use file extensions to denote content type

OR

• Use ‘Accept’ headers

Document!

• xDoc – Not so useful for end point docs

• I/O Docs – Great, but not linked to code

• Swagger – Very similar to I/O Docs• Grape – Ruby REST-like API

generator

Security

• Use something established• API keys for non-sensitive data

only• Username/password auth for

site based APIs• OAuth for server-to-server APIs• SSL for EVERYTHING sensitive

Summary

An APIs job is to make a developer as successful as

possible, as quickly as possible

Thanks!

Q&A?