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.

Transcript

1. What They Should Tell You About API Development @PHILSTURGEON ON APIS… AGAIN
3. SOAP != Bad Just… annoying
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
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"}
39. Document everything
40. Document FIRST
41. Test your docs!
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
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,
59. apisyouwonthate.com
60. Made in Production madeinproduction.com