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
   

   View Slide

2. View Slide

3. View Slide

4. View Slide

5. Try to work with the wind, don't fight
   it all the time.
   

   View Slide

6. Consistent.
   Stable.
   Well-documented.
   

   View Slide

7. APIs: Our experience as
   consumers
   

   View Slide

8. APIs: Our experience as
   producers
   

   View Slide

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

   View Slide

10. APIs: Our experience as
    producers
    

    View Slide

11. Application Programming
    Interface
    

    View Slide

12. View Slide

13. APIs = Constraints
    

    View Slide

14. Work with the constraints.
    

    View Slide

15. Remember these constraints are
    good for us too.
    

    View Slide

16. View Slide

17. View Slide

18. View Slide

19. Consistent
    

    View Slide

20. Consistent
    Consistent data
    

    View Slide

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

    View Slide

22. API Descriptions
    — JSON Schema
    — Open API (formerly Swagger)
    — RAML
    — APIs.json
    — API Blueprint
    — Postman Collections
    — Async API
    

    View Slide

23. Consistent
    Have one source of truth.
    

    View Slide

24. Have one source of truth.
    JSON Schema
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

28. It will be amaaazing!
    

    View Slide

29. Consistent
    Monitor your
    inconsistencies.
    

    View Slide

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

    View Slide

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

    View Slide

32. Monitor your inconsistencies.
    Technical deep dive
    

    View Slide

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

    View Slide

34. # Get a dog.
    get "/dogs/:dog_id" do
    authorize_access :users, :bots
    # finds the dog
    # renders the dog as JSON
    end
    

    View Slide

35. Then it will be amaaazing!
    

    View Slide

36. Stable
    

    View Slide

37. Stable
    Invest in upfront design.
    

    View Slide

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?
    

    View Slide

39. Remember:
    puppies APIs are
    for life not just for
    Christmas!
    https://www.flickr.com/photos/27587002@N07/5170590074
    

    View Slide

40. Design while the cost of
    change is low.
    

    View Slide

41. Stable
    A calm space.
    

    View Slide

42. metoffice.gov.uk
    

    View Slide

43. Stable
    

    View Slide

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

    View Slide

45. Minimize the negative
    impact
    

    View Slide

46. Well-documented
    

    View Slide

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

    View Slide

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

    View Slide

49. Well-documented
    Enable a holistic view.
    — Endpoints that are undocumented
    — Endpoints that are in any special phase
    — Anything to be deprecated
    — Dates
    

    View Slide

50. Well-documented
    Governance
    

    View Slide

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

    View Slide

52. Well-documented
    Internal guides
    

    View Slide

53. Well-documented
    API Styleguide
    

    View Slide

54. API Styleguide
    Avoid verbs and adjectives
    ❌
    GET /pets/most-recent
    ✅
    GET /pets?sort=date-added
    

    View Slide

55. API Styleguide
    Make exceptions deliberately
    GET /repos/:owner/:repo/releases/latest
    

    View Slide

56. Well-documented
    Internal guides
    

    View Slide

57. Well-documented
    Who is responsible for
    what?
    

    View Slide

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

    View Slide

59. It doesn’t have to be fucking hard.
    It just has to be consistent.
    Which is fucking hard.
    — Brett Sutton, Triathlon coach
    

    View Slide

60. Good luck!
    Thank you,
    @keavy
    

    View Slide