API Change Done Right

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

Transcript

1. May 2019 GitHub API Change Done Right Claire Knight Ecosystem API Lead
2. GitHub API Change Done Right - Claire Knight Background
3. GitHub API Change Done Right - Claire Knight Quality Versions Integrators Change…
4. GitHub API Change Done Right - Claire Knight Changes and Versions
5. 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!
6. 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
8. GitHub API Change Done Right - Claire Knight Integrators
9. 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.
10. 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 ❤
12. GitHub API Change Done Right - Claire Knight Quality and Consistency
13. 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
15. 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!