Principles of Awesome APIs and How to Build Them.

Keavy McMinn

November 18, 2019

Tweet Share

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