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
   

   View Slide

2. View Slide

3. SOAP != Bad
   Just… annoying
   

   View Slide

4. View Slide

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

   View Slide

6. Making an API
   100% REST is
   hard
   

   View Slide

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

   View Slide

8. Do you actually
   need REST?
   

   View Slide

9. Maybe RPC
   would be more
   appropriate
   

   View Slide

10. REST = Resources
    RPC = Commands
    

    View Slide

11. Using commands
    for resources sucks
    And vice versa
    

    View Slide

12. RPC REST
    GET /listCheeseburgers GET /cheeseburgers
    POST /createCheeseburger POST /cheeseburgers
    POST /updateCheeseburger PATCH /cheeseburgers/1
    POST /deleteCheeseburger DELETE /cheeseburgers/1
    POST /consumeCheeseburger ….
    

    View Slide

13. POST /SendUserMessage HTTP/1.1
    Host: api.example.com
    Content-Type: application/json
    {"userId": 5,"message":"Hello!"}
    

    View Slide

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

    View Slide

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

    View Slide

16. State Changes
    COULD be RPC
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

20. PATCH
    +
    State Machine
    

    View Slide

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

    View Slide

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

    View Slide

23. oh look ruby at a php conference
    

    View Slide

24. Sometimes a
    little RPC sneaks
    in...
    

    View Slide

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

    View Slide

26. There’s a reason
    Slack use RPC
    

    View Slide

27. View Slide

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

    View Slide

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

    View Slide

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

    View Slide

31. DELETE /channels/random/users/jerkface HTTP/1.1
    Host: api.example.com
    

    View Slide

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

    View Slide

33. So probably RPC
    for commands
    then?
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

37. View Slide

38. View Slide

39. Document everything
    

    View Slide

40. Document FIRST
    

    View Slide

41. Test your docs!
    

    View Slide

42. View Slide

43. View Slide

44. Maybe you don’t
    need HATEOAS
    

    View Slide

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

    View Slide

46. Hypermedia helps
    APIs outlive the
    average startup
    

    View Slide

47. RAD makes most
    attempts at
    versioning entirely
    pointless
    

    View Slide

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

    View Slide

49. Docker &
    Compose to the
    rescue!
    

    View Slide

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

    View Slide

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

    View Slide

52. View Slide

53. View Slide

54. https://github.com/crysalead/kahlan
    

    View Slide

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

    View Slide

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

    View Slide

57. View Slide

58. View Slide

59. apisyouwonthate.com
    

    View Slide

60. Made in Production
    madeinproduction.com
    

    View Slide