Upgrade to Pro — share decks privately, control downloads, hide ads and more …

What They Should Tell You About API Development

Phil Sturgeon
February 09, 2016

What They Should Tell You About API Development

As a refinement to his previously published book, the author of "Building APIs You Won't Hate" found that API books and training tend to introduce documentation, testing and caching as an after-thought, as if these are not important. However, some new experiences have shown that API development works best when these items are thought out first, as well as including a strong pragmatic approach to ensure the API solves real problems without getting stuck on the theory of how to "properly" create it.

Other pragmatic talking points include: Why and how documentation first can stop your team(s) from getting violent, when is REST not what you want, why is hypermedia sometimes a distraction, convenient ways to avoid versions in your API or at least postpone it, and comprehensive but simple endpoint integration testing beyond trivial examples.

Phil Sturgeon

February 09, 2016
Tweet

More Decks by Phil Sturgeon

Other Decks in Technology

Transcript

  1. What They Should Tell You About API Development @PHILSTURGEON ON

    APIS… AGAIN
  2. None
  3. SOAP != Bad Just… annoying

  4. None
  5. Don’t confuse REST with a metric of quality

  6. Making an API 100% REST is hard

  7. http://martinfowler.com/articles/richardsonMaturityModel.html

  8. Do you actually need REST?

  9. Maybe RPC would be more appropriate

  10. REST = Resources RPC = Commands

  11. Using commands for resources sucks And vice versa

  12. RPC REST GET /listCheeseburgers GET /cheeseburgers POST /createCheeseburger POST /cheeseburgers

    POST /updateCheeseburger PATCH /cheeseburgers/1 POST /deleteCheeseburger DELETE /cheeseburgers/1 POST /consumeCheeseburger ….
  13. POST /SendUserMessage HTTP/1.1 Host: api.example.com Content-Type: application/json {"userId": 5,"message":"Hello!"}

  14. POST /users/5/send-message HTTP/1.1 Host: api.example.com Content-Type: application/json {"message":"Hello!"}

  15. POST /users/5/messages HTTP/1.1 Host: api.example.com Content-Type: application/json {"message":"Hello!"}

  16. State Changes COULD be RPC

  17. POST /trips/123/start HTTP/1.1 Host: api.example.com

  18. POST /trips/123/finish HTTP/1.1 Host: api.example.com

  19. POST /trips/123/cancel HTTP/1.1 Host: api.example.com

  20. PATCH + State Machine

  21. PATCH /trips/123 HTTP/1.1 Host: api.example.com Content-Type: application/json {"status":"in_progress"}

  22. PATCH /trips/123 HTTP/1.1 Host: api.example.com Content-Type: application/json {"status":"complete"}

  23. oh look ruby at a php conference

  24. Sometimes a little RPC sneaks in...

  25. POST /invitations/some-code/join HTTP/1.1 Host: api.example.com

  26. There’s a reason Slack use RPC

  27. None
  28. DELETE /users/jerkface HTTP/1.1 Host: api.example.com

  29. PATCH /users/jerkface HTTP/1.1 Host: api.example.com Content-Type: application/json {"status" : "kicked"}

  30. PATCH /users/jerkface HTTP/1.1 Host: api.example.com Content-Type: application/json {"status" : “kicked",

    "kick_channel" : "catgifs"}
  31. DELETE /channels/random/users/jerkface HTTP/1.1 Host: api.example.com

  32. DELETE /channels/random/users/jerkface HTTP/1.1 Host: api.example.com Content-Type: application/json {"reason" : "kick"}

  33. So probably RPC for commands then?

  34. POST /channel.kick HTTP/1.1 Host: api.example.com Content-Type: application/json Authentication: Bearer moderator_token

    {"user" : "jerkface", "channel" : "catgifs"}
  35. POST /channel.leave HTTP/1.1 Host: api.example.com Content-Type: application/json Authentication: Bearer user_token

    {"channel" : "catgifs"}
  36. POST /user.ban HTTP/1.1 Host: api.example.com Content-Type: application/json Authentication: Bearer moderator_token

    {"user" : "jerkface"}
  37. None
  38. None
  39. Document everything

  40. Document FIRST

  41. Test your docs!

  42. None
  43. None
  44. Maybe you don’t need HATEOAS

  45. http://martinfowler.com/articles/richardsonMaturityModel.html

  46. Hypermedia helps APIs outlive the average startup

  47. RAD makes most attempts at versioning entirely pointless

  48. Don’t trust self- testing apps/services

  49. Docker & Compose to the rescue!

  50. TDD is the easiest way to build a complex HTTP

    API
  51. Describe-it syntax helps you write complex tests easily

  52. None
  53. None
  54. https://github.com/crysalead/kahlan

  55. Don’t let clients hit staging for dev Again, probably use

    Docker/Vagrant
  56. ?include=literally, everything,in,the, goddam,database, what,is,happening, so,slow,help,me, database,server,is, on,fire,nothing,we,

  57. None
  58. None
  59. apisyouwonthate.com

  60. Made in Production madeinproduction.com