Upgrade to Pro — share decks privately, control downloads, hide ads and more …

API Change Done Right

API Change Done Right

*Spoiler Alert* - _right_ can be achieved in many different ways!

Claire

May 07, 2019
Tweet

More Decks by Claire

Other Decks in Technology

Transcript

  1. GitHub API Change Done Right - Claire Knight Changes Adding

    a new REST endpoint Adding a field to a GraphQL object Previews to wrap new functionality BUT many more changes are breaking ones!
  2. GitHub API Change Done Right - Claire Knight Versioning vN

    in URL Timestamps Continuous Accept Headers n+1 version numbers in the host or URL path Very similar to n+1, and again in the URL Relies on client negotiation of what they can handle Version details sent as part of Accept headers
  3. GitHub API Change Done Right - Claire Knight Hyrum’s Law

    With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody.
  4. GitHub API Change Done Right - Claire Knight • Published

    schedules for deprecations • Good communication and announcements • Example code • Migration paths • A place for asking questions and getting and giving feedback • Actually responding to their feedback in a thoughtful way ❤
  5. GitHub API Change Done Right - Claire Knight Maintaining the

    API Complete Testing Review Changes Tooling Ensure all public endpoints have tests Also ensure GraphQL objects are covered by test queries Engineering needs to own the Public API Automated as much review as possible
  6. API Change Done Right - Claire Knight GitHub Closing Thought

    An API is just the language to communicate with a service. And languages constantly evolve. Additions, change of meanings, lack of use… APIs are no different!