In my previous blog post I gave a summary of the answers to many API questions, which I asked at two conference talks. One of the worst-rated questions was the implementation of life-cycle management in organizations.
I have experienced this myself (mostly as an observer) in many organizations. The most famous statement was made by an enterprise architect at a large insurance company, who told me that they were nearly done with their SOA initiative; only versioning was missing. This statement is a bold example on what often goes wrong. It was stunning on so many levels that I want to discuss them shortly here.
Life-Cycle is more than Versioning
The first misconception I frequently encounter is that life-cycle management is the same as versioning. I am sure that we need versioning and that it makes sense to version the API contract separately from the API implementation. However, life-cycle management is more than assigning a version to an API: You need to specify rules when and how to do different changes. When am I allowed to do backwards-compatible changes? How do I communicate them? When am I allowed to do breaking changes? How do I make them? Versioning is a tool for communicating changes and the impact of changes both for developers and (if version numbers are used to syntactically break compatibility) API clients. But only slapping a versioning number on things does not solve your life-cycle problem!
We love building things but not managing them
When building up API programs or APIs in general, people are fascinated by and focus on building things. How can APIs be brought to market faster and with less effort? How do we design API contracts? How do we get clients to use our APIs? These are all valid problems to tackle, and they are fun because as (software) engineers we like to build things. Changing things is an afterthought and in general it is postponed after the API has been released. There might be some guidelines for what constitutes a breaking change and that this is somewhat bad but there is hope that things will be figured out along the way.
We love creating things but not phasing them out
The (software) engineering mindset does not like to think about changing stuff (i.e., our APIs) but in general it is not thought of how to discontinue an API (or change it in a really breaking manner, which equals to discontinuation plus a release of an API with similar business functionality). I was asked once how to move customers from a file-based API to a new HTTP-based offering. How to change authentication because the old method was deemed insecure by current standards. The list of reasons why you break an API is endless. However, very often people expect to just do backwards-compatible changes and do not prepare their API clients to migrate.
But I heard that it is best practice to stay backwards-compatible forever
I think that telling people that you can stay backwards-compatible for an indefinite time is best practice and the way to design and evolve your APIs. Especially with the rise of Restful HTTP many people repeated and promoted this thinking, which was clearly wrong and contradicted by experience long before. The best (or worst) example of this thinking was that a company – and thus its Web site browsable by a user - does not change enough to serve as a completely different company. Just have a look at Nokia which have changed their offerings – and consequently their target audience and published information – in their company history. But this argument is a strawman in itself: While there are changes to the business offering that might lead to a breaking change, very often regulatory and compliance topics will force incompatible changes. Just think about early online banking in Germany (local bank account numbers, bank number and German mark) compared to today’s online banking (international bank account numbers and Euros). While it is best practice to not unnecessarily force breaking changes on your clients, at some point you want to and/or must break compatibility to move forward.
What to do?
If we take all these things together, the first thing to do is to define how APIs will be changed both backwards-compatible and incompatible in the future. There are many options how to do this but before putting your API in production you need to have this done! If this is not in place, API clients will assume that the API is offered in a backwards-compatible manner forever and nasty discussions will follow if you are not the dominant market player. But even in that case it is much better for everyone and your reputation to have clarified this beforehand. Essentially, you need to manage your clients’ expectations. The earlier you do this, the easier it will be!
What are your main problems with API development and platforms? Erik Wilde and I have created a small self-assessment available to you for free to find out! Please try and share it!
|
<<< Previous Blog Post API Patterns help you with Life-Cycle Management |
Next Blog Post >>> What are Challenges with our APIs? |