Principles of Awesome APIs and How to Build Them.

Transcript

1. Principles of Awesome APIs and How to Build Them. Keavy McMinn, Fastly RubyConf 2019 @keavy
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
13. APIs = Constraints
14. Work with the constraints.
15. Remember these constraints are good for us too.
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