On a lazy Sunday afternoon, I was bored and decided to start a new game on my PS4. I recently bought a few, one of which was God of War. The latest edition of the game is based entirely on the Norse mythos. As I played along, the game’s concept and the different worlds fascinated me in the Norse cosmology.
API Design fundamentals
Naturally, I decided to do some reading and came across the Nine Worlds and a cosmic tree, Yggdrasil, which plays an integral role in acting as a geographical center, connecting all the worlds and maintaining balance. The well-being of the cosmos depends on the well-being of this tree and the health of the nine realms.
Here’s an infographic that gives a simple, yet the detailed look of how it holds the nine worlds together in its branches and roots.
My “software-engineering trained” mind almost instantly drew an allegory, a poem if you will, for the RESTful API world and attempted to outline the fundamental and crucial attributes of an API through which we can perfectly establish its integrity and maintain balance.
In our ever-growing distributed API cosmos, we must find our very own “Nine Worlds” and “Yggdrasil” for maintaining harmony and balance.
Without getting into too much detail, here are the nine attributes of APIs as the “Nine Worlds.”
1. Simplicity
“Simplicity is the ultimate sophistication.” – Leonardo Da Vinci
Perhaps no better quote when it comes to the design of an API. When you start putting together the elements of a beautiful API, it is important to keep the naming of models, endpoints, parameters, errors and miscellaneous as simple as possible, while giving enough information. This makes the API easy to read and consume, for consumers and developers alike. Here’s a good way to remember this.
2. Documentation
This is kind of obvious, but it is important to understand what “documentation” really entails. Great APIs can be distinguished from good APIs by the level of documentation. Comprehensive documentation not only helps the consumers, but it also helps the developer community. It also becomes the contract between you, as an API provider and a consumer. The success of API-based applications depends heavily on good, up-to-date documentation!
3. Security
It would be redundant for me to point out why security is paramount for any web-based application. Check out the recently published OWASP Top 10 2019 API Security Threats. Authorizing/authenticating every single request over the web is essential to stay secure for any API provider. Many companies are now adopting the “shift left” security principle in their API software development lifecycle and DevOps processes. You can find an article about it by Twistlock.
4. Versioning
Every API goes through changes. Often, developers shoot themselves in the foot when they make a breaking change (major or minor) and don’t update and release a new version of the API. This impacts an existing client’s integration and ends up breaking its functionality. There are some good guidelines around versioning that developers can follow when making non-breaking or breaking changes to an API.
5. Standardized error handling and logging
To make your API consumer’s life easier, it is important to stick to standards when returning an error response code and let the user know there has been a failure. Crafting error response messages can be tricky, but they should be as clear and concise as possible. And when you combine the error message with a standard HTTP status code, it’ll immensely help in clarifying the failure and hint what the intended functionality is, in case of a human error.
Logging of every API request and response through the system should be a no-brainer and it’ll especially aid in identifying and debugging failures, along with the dreaded “500 Internal Server Error.”
6. Scalability
Many legacy enterprises are going through a digital transformation and APIs enable speeding up this transformation as monolithic products are being broken down into easily manageable microservices that constantly communicate with each other. For the same reason, APIs must be designed with scale in mind. To satisfy the demand of highly usable and available APIs while having a realistic expectation of the high volume of requests in the current software ecosystem, scalability should be considered a core attribute when designing an API.
7. Statelessness
For an API to be scalable, it also must be stateless. In a distributed microservices architecture, to maintain concurrency and fault-tolerance, servers are usually replicated. And storing no state-related data means no session information or related dependencies, which enables any number of clients to connect at any time. And stateless APIs also forces the clients to always validate their session.
8. As a product
You’ve all heard of the quip “It’s not a bug, it’s a feature.” Now we can go one step further and say, “It’s not a feature, it’s a product.”
When you foster a culture of building your API as a product, you reimagine APIs from being a technical feature to a marketable business offering. This mindset immediately makes you treat every consumer (internal or external) of your API as a buyer, thus leading to building better investment strategies and a clear product roadmap. Your stakeholders will also be more involved when your API is a business asset and not just a collection of the codebase.
9. Reliability
Reliability is what sells a product. And as we have deduced from the previous point, building safe, reliable APIs is what keeps the users happy and come back for more. And when developers switch roles to consume other APIs, most seem to agree that reliability is APIs most important feature. Monitoring your APIs usage, understanding consumption patterns and mapping out trends can help optimize your APIs and design better ones for your next solution.
Leaving you with some final thoughts, good API design is not limited to only these nine, as this is not an exhaustive list. As you can see in the infographic above, there are a lot more elements (Gods, The Eternal Flame, The Rainbow bridge) which are essential for the well-being of the cosmos. But that is for another day.
Read all about the importance of API Design.
Follow us on social