Evolutionary not Revolutionary API Change

Once created, an API will undergo growth and change. It's essential to focus on API design throughout this time. Don't release things too early, but don't keep previews running forever. Integrators need to know they can trust the API. But also don't consider deprecations a bad thing. Breaking changes are a sign of a healthy, actively used and maintained API. They are necessary to ensure long term growth and stability of your API. This talk covers some strategies you can take to achieve this, and how we do some of these things at GitHub. While integrators want stability, if you focus on being responsive integrators will generally help you to help them.

Transcript

2. Evolutionary not Revolutionary API Change Dr Claire Knight
3. Introduction
4. … how to write “good” REST endpoints … how to write GraphQL resolvers … how to code any aspect of your API This talk is not…
5. … thinking about your API as a product … not fearing change; as integrator or owner! … enabling your API to grow and evolve However this talk will cover…
6. Change
7. • Change is inevitable! • APIs are just a means of communication with a service • Language (a means of communication) evolves; why shouldn’t APIs?
8. 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. http://www.hyrumslaw.com/
9. The real question is to how to achieve change in a way that works for the API itself and for those who use it?
10. Product Thinking
11. … so it should have it’s own roadmap … therefore it should be as cohesive as possible … so what works for one API may not for another … and has business concerns as well as technical An API is a product...
12. … plan for change, but keep things incremental … set expectations that change will happen … avoid breaking changes where possible … consider using very granular versioning Some things to think about...
13. … consistency is easier the earlier you begin … scale affects the impact of any change … use previews properly (time limited!) … don’t neglect deprecation Even more things to think about...
14. Summary
15. An API is a product which must be maintained, albeit with some extra technical parameters. Focus on consistency of use and of announcements. Each API is individual so don’t blindly apply things from one to another. Pick and choose what you need keeping the business, integrators, and internal developers in some level of balance.
16. Remember - an API is a Product!