APIs and Breaking Change: How Implementing APIs Forces Important Business Decisions
I talked to Gareth Jones, Principal API Architect for Microsoft Education, to find out about how implementing APIs forces business decisions. Jones previously was the API Architect for Microsoft Graph and OneNote, built Application Lifecycle Management (ALM) tools, ran the Visual Studio ecosystem dev team, co-created the DSL Tools for modeling with domain-specific languages in Visual Studio, built APIs for UML designers, and much more. Jones is giving a keynote at ASC 2019 (Oct 15-17, Vancouver, BC) titled “Keynote: Your API Spec Isn’t Worth the Paper It’s Written On.”
Isn’t implementing a new API scheme or a large integration project primarily a technical undertaking?
“I like to think it’s about the intersection of business and technology. A great example is when it comes to ‘breaking change.’ Breaking change is when you do something that departs from what was done in the past, and things that used to work break. Eventually, all companies do this. The decision is simply: Is breaking change something that you just let happen or do you intentionally plan for it?
Fundamentally, APIs are about businesses interacting. API conferences often look at APIs from a technical point of view. Discussions in a pub focus on technical tools and minutia. It all appears technical.
It’s not. It’s really about making good business decisions.
For example, APIs can often be thought of as enabling self-service, replacing big, expensive integration projects, whether between internal organizations or between companies. But to really be effective in the long run it’s not just that contract, it’s a coming together to understand each other’s objectives and how both sides will function in the future.
Some businesses can be comfortable with different levels of strictness about breaking change. If you know your API is at the mission-critical center of your customers’ business you probably need to be more risk-averse than if you are delivering something which is used to add flourishes around the edge. Or maybe they paper over the problems with lots of consultants who follow up with support. Or maybe they know that their customers will stick with them because they will not upgrade, they’ll just stay on stable older versions as long as possible.”
Can newer tools using Open API schemas help?
“Tools can absolutely help spot potential breaks in an api when your schema changes. However, not everything is codified and easy for tools to identify. Some things are harder to document. An API that returns information on a collection of ‘Bikes’ for rent might return a set of any size. What if the customer has built a UI that expects values generally in the range of 1-100? Unexpectedly, the provider of the API does an acquisition. Suddenly, the numbers of Bikes increases radically to, say, 27,000 when the API is used. The API still works, it’s not broken at all by its specification. But the UI that the customer uses is broken because I can’t page through that many items effectively.
That’s a breaking change. Technically, not a breaking change for the API. But it is for the customer.
The question is, do you want to do this on purpose, or by accident?
It’s a business decision, not a technical one, and making it proactively will help your business, even in the near term.”
Can APIs and privacy concerns co-exist?
“Privacy is a huge force in technology. It all comes down to the right balance. Understanding how customers are using APIs in a deep way can appear to conflict directly with privacy. Having the right model for consent and governance is the key here. If the owner of the data is able to effectively control who it is shared with via APIs then we can still have ecosystems while respecting privacy.”
Does that mean that testing is critical?
“Well, yes. But everyone knows that they should ‘test more.’ It still doesn’t always protect you.
For example, if I do a lot of careful testing on an API that returns images, but I use sample images of cats from the internet in all my testing I may get very good results. But a key customer may be working with high-res studio photos and I hadn’t tested with images that large. Everything breaks because something in the stack can’t cope when pushed. Again this isn’t something we’re likely to have specified. It’s more that it breaks conventions.
Lorinda Brandon has often talked about the impact of chaos in distributed systems, but we can turn it around and make it work for us in hardening APIs. No amount of preparation can foresee all the possible issues in a real production deployment. We can build a chaos-driven test framework to send a wide range of combinations of ‘crazy’ values. This way you inflict your APIs with unexpected values intentionally to test system resilience and learn from the experience.
If you provide an API that can handle wild values, they will be able to handle more common usage when they get to production.”
What Sessions Are Worth Attending at ASC 2019?
To get more information around breaking change and chaos, I highly recommend the following three sessions:
For a wide-ranging discussion where you can ask questions yourself:
For details on larger implementations (Oracle and Microsoft):
For more details beyond this interview, my keynote:
This article originally appeared here.
