Principles of Awesome APIs and How to Build Them.

Principles of Awesome APIs and How to Build Them.

B47b288784fda77a94aeb234ca743c24?s=128

Keavy McMinn

November 18, 2019
Tweet

Transcript

  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

    it.
  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

    do.
  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!

    https://www.flickr.com/photos/27587002@N07/5170590074
  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