Have you seen some of the images of deep space taken by the James Webb telescope? As much as these images make me marvel at the universe, they are also a testament to the capability of today’s space engineering, which is capable of designing, building, and operating a telescope on a spacecraft far from Earth that delivers these images.

Think about it, once such a spacecraft has been launched and is out in space, it needs to work flawlessly! If something unexpected happens, you cannot just order a service technician to check what’s wrong. Once launched, spacecraft are simply out of reach, travelling far away and at high velocity, which makes it impossible to change any aspect of their design. And with this in the back of their mind, space engineers do everything to get them prepared for launch day. They know they have just one chance to get it right.

And with APIs? At first sight, the engineering of APIs is much different from the engineering of a spacecraft. After an API has been launched, you could easily change it. The code is right there, the gateway configuration is at your fingertips, and pushing out a change is a matter of seconds.

But should you? And I am not talking about fixing bugs — of course, you should fix them — I am talking about design changes. Unlike with spacecraft, all the artefacts you need for a change seem to be available and within reach — so why wait?

When an API gets published, it starts to get used by API consumers. It just means that the API consumers write application code that calls the API. And in this code, they "bake in” a reasonable assumption about the API: that it will stay exactly as it was at development time. This assumption is completely reasonable because it allows making an API call in a simple manner. But this assumption also makes applications very sensitive to changes in the API specification. You could say that most applications are inflexible to API changes and that even the slightest change will break them. By and large, applications rely on unchanged APIs. And today, with APIs being used in business-critical applications, many businesses depend on the used APIs to run in exactly the same way as they did the day before.

As a side note, the HATEOAS principle (https://api-university.com/blog/rest-apis-with-hateoas/) would not require you to make the above assumption, because it introduces a level of indirection and dynamic discovery of the API endpoint. But it adds to the complexity for the API consumer and is thus not widely used in practice. So HATEOAS is excluded from this article.

When you have a number of API consumers, some of them depend on one set of data fields, and others depend on another set of data fields. For each aspect of your API, you can find an API consumer that depends on it. And as Hyrum's Law tells us, this dependency is not limited to the documented features in your API contract (i.e., your Open API specification) but pertains to any observable behaviour of the API. With a sufficiently large group of API consumers, you cannot easily change the design without breaking some code and creating problems for at least one of the API consumers.

Even though we could readily change APIs — we should not do it. Once an API is published, API consumers depend on it, and API changes will break their application. Or as Amazon CTO Werner Vogels phrased it in his best practices for APIs: “APIs are forever.” They cannot be changed.

Be agile before launch day and conservative afterwards.

It helps to take a space engineering mindset and think of an API as a spacecraft. Before you launch, you can change the design, iterate on it and work on it in an agile, iterative fashion, where feedback is readily incorporated into its design. The same holds for an API before publication when it is in the initial design and prototyping phase — maybe even in the implementation phase. But launch day changes everything. After launch, the spacecraft is physically out of reach for design changes. And for APIs, you should think about your deployment to production and publication of the API in the same way. But since all artefacts are physically within reach, you need to set up some rules to prevent design changes.

And if you (or an important API consumer of yours) wanted to change the API anyway? Well, you would need to handle it in exactly the same way as you would change a spacecraft: You would go to the work shed and build a new version of the spacecraft — with the new, improved design — and you would launch it into space. Sounds costly? It would not only be costly for a spacecraft, but also for an API. When you introduce a new version of an API, while the old version remains as is, the effort for running and maintaining the API doubles.

As for the design of a spacecraft, you need to get the design of your API right the first time! It will be out there forever. Designing an API is not "rocket science," but the mindset of space engineering will help you to create dependable APIs that your API consumers can rely on.

Editor's note: To learn more about this topic, register for API Con Berlin 2022 here and attend Matthias' talk on API Versioning on October 19th at 11:30 CEST.