Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

API Design


Published on

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

Published in: Technology, Business
  • Be the first to comment

  • Be the first to like this

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 srs Dom Udall
  3. 3. Apologies
  4. 4. Where I’ve Stolen This From
  5. 5. RESTverb noun
  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 Error
  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:
  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?