$30 off During Our Annual Pro Sale. View Details »

Principles of Awesome APIs and How to Build Them.

Principles of Awesome APIs and How to Build Them.

Keavy McMinn

November 18, 2019

More Decks by Keavy McMinn

Other Decks in Programming


  1. Principles of Awesome APIs and How to Build Them. Keavy

    McMinn, Fastly RubyConf 2019 @keavy
  2. None
  3. None
  4. None
  5. Try to work with the wind, don't fight it all

    the time.
  6. Consistent. Stable. Well-documented.

  7. APIs: Our experience as consumers

  8. APIs: Our experience as producers

  9. APIs: Our experience as producers Fixing it would actually break

  10. APIs: Our experience as producers

  11. Application Programming Interface

  12. None
  13. APIs = Constraints

  14. Work with the constraints.

  15. Remember these constraints are good for us too.

  16. None
  17. None
  18. None
  19. Consistent

  20. Consistent Consistent data

  21. ✅ { "admin": true } ❌ { "admin": "1" }

  22. API Descriptions — JSON Schema — Open API (formerly Swagger)

    — RAML — APIs.json — API Blueprint — Postman Collections — Async API
  23. Consistent Have one source of truth.

  24. Have one source of truth. JSON Schema

  25. JSON Schema committee gem https://github.com/interagent/committee

  26. JSON Schema PRMD gem https://github.com/interagent/prmd

  27. JSON Schema Online examples http://bit.ly/heroku-schema

  28. It will be amaaazing!

  29. Consistent Monitor your inconsistencies.

  30. Monitor your inconsistencies. Compare what you say and what you

  31. Monitor your inconsistencies. Try a portion of your API

  32. Monitor your inconsistencies. Technical deep dive

  33. Monitor your inconsistencies. Technical deep dive https://github.com/whitequark/parser

  34. # Get a dog. get "/dogs/:dog_id" do authorize_access :users, :bots

    # finds the dog # renders the dog as JSON end
  35. Then it will be amaaazing!

  36. Stable

  37. Stable Invest in upfront design.

  38. Invest in upfront design. — What will users do with

    it? — What does your business need from it? — What does it look like? — What will you call it?
  39. Remember: puppies APIs are for life not just for Christmas!

  40. Design while the cost of change is low.

  41. Stable A calm space.

  42. metoffice.gov.uk

  43. Stable

  44. Change itself is not necessarily bad. Negative impact from change

    is bad.
  45. Minimize the negative impact

  46. Well-documented

  47. Well-documented Inform users about everything, early and often

  48. Well-documented Then remember that people don’t read.

  49. Well-documented Enable a holistic view. — Endpoints that are undocumented

    — Endpoints that are in any special phase — Anything to be deprecated — Dates
  50. Well-documented Governance

  51. Well-documented Shared understanding is easier when it’s all written down.

  52. Well-documented Internal guides

  53. Well-documented API Styleguide

  54. API Styleguide Avoid verbs and adjectives ❌ GET /pets/most-recent ✅

    GET /pets?sort=date-added
  55. API Styleguide Make exceptions deliberately GET /repos/:owner/:repo/releases/latest

  56. Well-documented Internal guides

  57. Well-documented Who is responsible for what?

  58. Well-documented Who gets a say in decision making?

  59. It doesn’t have to be fucking hard. It just has

    to be consistent. Which is fucking hard. — Brett Sutton, Triathlon coach
  60. Good luck! Thank you, @keavy