API Design

901 views
854 views

Published on

Basics of good API design (font not embedded correctly, so sorry it looks nasty!)

Published in: Technology, Business
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
901
On SlideShare
0
From Embeds
0
Number of Embeds
16
Actions
Shares
0
Downloads
14
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

API Design

  1. 1. API Design
  2. 2. Who Am I?Bournemouth Uni GraduateClock – Software EngineerSynth Media – Technical Director@synthmedia – Business@domudall – Srs@dmno – Not so srshttp://github.com/domudall Dom Udall
  3. 3. Apologies
  4. 4. Where I’ve Stolen This Fromhttp://www.slideshare.net/MikePearce/api-anti-patterns-4920731 https://vimeo.com/13922981 http://mikepearce.net/
  5. 5. RESTverb noun
  6. 6. GET/POST Tunnelling• GET • TRACE• POST • OPTIONS• PUT • CONNEC• DELETE T• HEAD • PATCHhttp://en.wikipedia.org/wiki/HTTP_method#Request_methods
  7. 7. PUT or POST “The client uses PUT when it’s in charge ofdeciding which new URI the resource should have. The client uses POST when the server is in charge…” O’Reillys RESTful web services
  8. 8. Responsible Responses• Send the correct content type header• Don’t send mixed responses• Use the correct response code!
  9. 9. Response Codes • 1xx – Informational • 2xx – Successful • 3xx – Redirection • 4xx – Client Error • 5xx – Server Errorhttp://en.wikipedia.org/wiki/List_of_HTTP_status_codes
  10. 10. Caching• Between application and database• In the application itself• Using an API proxy• CDN for large static content
  11. 11. Cookies• NO!• REST is meant to be stateless• One change to token handling can render all tokens useless
  12. 12. HATEOASHypermedia as the engine of application state Huh?
  13. 13. HATEOAS• Clients shouldn’t be building URIs• API responses return end points• API end points can change without disruption to the client
  14. 14. GET: http://api.startup.co/users
  15. 15. Versioning• Grey area• Goes against HATEOAS• Can either: – Versioning all URIs – Not versioning main URI – Not versioning at all
  16. 16. Document Extensions • Use file extensions to denote content type OR • Use ‘Accept’ headers
  17. 17. 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
  18. 18. 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
  19. 19. Summary An APIs job is to make a developer as successful aspossible, as quickly as possible
  20. 20. Thanks!
  21. 21. Q&A?

×