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