Download - 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?