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

    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