Have you ever proudly released an API only to realise months or years later that it had design flaws which made it a pain to work with? Here are some API design principles that help you design better APIs based on nature.
It’s entirely possible to design APIs that are a joy to work with. But you have to change the way you think about your API. Don’t treat it like a machine, treat it like a living organism instead.
These are the API design principles covered in this article:
- How your API evolves over time
- Managing API evolution with versioning
- How to you can manage technical debt and keep your API flexible
- How your API forms a synergy with its consumers
- That your API only exists in relationships
The product life cycle for APIs
Your API is not a static thing, it changes over time. Like other products your API has a limited lifespan. First it is designed and implemented. Once it is released it hopefully grows until it reaches its maturity.Until eventually growth slows down. Your API will reach an equilibrium where competitors might steal market share from you cancels out your slower growth. Eventually the market, your customers or competitors move on and your API starts a decline.
Like a living being your API is born, grows, matures and eventually dies. Plan for each stage accordingly.
Thinking of your API as a living thing is one of my nature inspired API design principles. The life cycle of your API is almost a law of nature API design. As the creator of this organism you can plan for each stage of its life and not get caught by surprise.
Design your API for growth
Your API grows and evolves over time. If your API does not get a foot in the market it means you’re sitting at a dead end branch of evolution. Many problems come about at the growth stage of your API.
- Demand outweighs your growth
- Your API can’t evolve as fast as the environment
- Too much uncertainty creates inertia
Use API versions for API evolutions
Your growing API becomes better at solving a given problem. With every new mechanism to deliver value your API changes. We need API versioning to evolve safely. If you version your API from day one it makes it much easier to manage changes. You can introduce new behaviour in the latest API version without having to break your head over backwards compatibility.
The de-facto standard for versioning is semantic versioning (SemVer). You probably have seen SemVer already. A version number looks like this: 2.0.1. That first number is for major releases (breaking changes), the second is called minor (backwards compatible changes) and the last number is called patch (for backwards compatible bug and security fixes). For a REST API your consumers don’t need to care about backwards compatible changes (minor and patch). That’s why you often see APIs only exposing their major version in the URL like v1, v2 and so forth.
You can make it clear in your API documentation that you are adhering to semantic versioning and that API version changes include breaking changes.
Prune your API to let it grow
A healthy tree needs pruning so it can grow stronger and sprout new branches. Likewise your API can evolve only if you prune it. If you keep adding to your APIs functionality you will encounter multiple issues:
- Maintenance efforts steadily increases
- You introduce inconsistencies making the API harder to understand and use
- Some functionality is mutually exclusive to new functionality
Over time the older API branches will accumulate technical debt and legacy code. You need to actively manage this technical debt to keep your API functioning.
Why you need to fade out old API versions
Nature constantly revents itself. Over time this replaces other, less efficient branches of nature. This evolution and replacement are wonderful API design principles we can learn from nature. Your new API version attracts more usage with new functionality while still supporting existing use cases. So over time your older API versions become less and less valuable. It’s common that both API versions access the same underlying data. Transforming the data between different API formats can become increasingly cumbersome. To the point that developing your API becomes a real pain. Eventually they will bring so little value and cause so much maintenance that you just want to get rid of them.
Never change a running system is what your API consumers think when they face a mandatory upgrade
You will struggle to get existing API users to upgrade. The new functionality in your latest API version might not be important enough for them to go through the hassle and expense to upgrade. This is a death grip for your API. You need your customers to upgrade to allow your API to evolve and prune old branches.
Your API forms a synergy with your API consumers
Do you know what lichens are? Lichens are two separate organisms that function together to accomplish things neither one could do on their own. Lichens are our next great example for nature-based API design principles. You enter a similar synergy with your customers because your customer can’t solve certain problems without your API and your business won’t survive without them using your API.
The downside of this is that you can only evolve together. If your customers stick with an outdated API version which causes you a lot of maintenance headaches, the synergy will not thrive. So you either convince your consumers to use the latest version or you break the synergy.
What forced upgrades mean for your customers: risk, expenses and struggle
Understand that many businesses struggle for resources. Mandatory upgrades can come with huge pain and little benefit. So make it as easy as possible for your API consumers to upgrade. Remember that your API can’t survive without its API consumers.
- Ensure downward compatibility wherever possible and introduce breaking changes only when absolutely necessary.
- Publish upgrade guides that help the developers on the other end to use your latest API version. Show them how to complete their workflow with your latest API.
- Make it crystal clear what’s not possible anymore and explain why. This can lead to a lot of frustration so handle it with humility and transparency.
API deprecation and sunsetting helps to prune your API
This conflict of mandatory upgrades can be damaging for your relationship with API consumers. The only way to avoid this is to make it clear from the beginning of your relationship that this API will be turned off at a given date.
You know when it’s time to let go of an old API version. Let your customers know too and send an HTTP Deprecation header. When you decide on a date to turn off your old API versions you can send an HTTP Sunset header as well to let your customers know at what point they won’t be able to use your API anymore.
But don’t rely on HTTP headers alone, remember that there is a human on the other end of your API. Make sure to add your deprecation warnings and sunsetting dates to your documentation and communicate them on various channels.
Include an immune system in your API design
Life has a way to sustain itself but that doesn’t mean it can thrive under all circumstances. Thriving organisms have layers of protections to sustain themselves. Give your API the same defense mechanisms. The immune system is a great API design principle we can apply to our APIs.
Your API needs strong security if you don’t want it to get crushed by a bad actor. You want to create a trusted environment where both your API and your API consumers live in harmony. That means using strong encryption and using access tokens amongst other things.
The dose makes the poison. Know what is a poisonous dose for your API.
Your API can get too much of a good thing. Design your API in a way that it can create maximum value without it suffering. Rate limiting, also known as throttling, can help you do that and it is an API design principle again inspired by nature. Place quotas on how often your API can be called by a single consumer or IP address to prevent abusive behaviour or simple programming mistakes of your API consumers. When your API dies, it dies for all API consumers so don’t let a single consumer have a negative impact.
Uncontrolled growth of your API – could it be cancer?
Uncontrolled growth in an organism is called cancer. We have to ensure the same doesn’t happen to our API. We need to stay on top how our API is being used.
Black mirror is a TV show where each episode depicts a dystopian world enabled by technology. Think of social networks these days. Surely its widespread usage reflects the value it has brought to our lives but at the same time they amplify our anxieties, are used to manipulate elections, abuse our privacy and sell our data.
Make sure your API can not be used for unethical purposes. Even though we are more inclined to dream of the best case scenarios we have to set up our API to prevent the worst case scenario. Your DNA is a relatively resilient structure that can prevent faulty, uncontrolled cell division. By the same token you can design your API around the same principle and make it resilient to uncontrolled, unethical growth.
Looking into nature for solid API design principles
There are many API design principles that we can learn from nature. Your API forms a synergy with your customers. Evolve your API with versioning from the very beginning of its life. Then keep your API healthy by shedding the old layers with deprecation and sunsetting older API versions. Be sure that your API is and stays fit for purpose and serves a clear customer need. Above all prevent anyone from using your API to cause harm. If we can apply those nature based API design principles we can build APIs that live long and prosper.