7 Essential things to think about when building an API | Insights – Reshape Digital 

Building an API is clearly easy, you can have a start up project with two clicks, start coding and in two weeks you have your MVP. Though, starting super fast and building on the wrong infrastructure can cause a lot of damage. In time, having to build the base afterwards or to fix something on a failed layer structure is both time consuming and costly. In order to avoid all of this, think long term. Build your API with the future in mind, think that things can change quick, but your API needs to adapt quicker, think that you will have millions of users to serve, but they don’t have time to waste. To achieve all of this, I consider you need to judge everything about your API in two terms: sustainability and scalability.

From my point of view, there are seven large and important components that we need to take into consideration when developing an API for the long run. Security, Architecture, Testing, Logging, Documenting, Versioning, Caching.

Security 🔒

If you are not building a public API, giving anonymous access to it, you certainly need some sort of security for allowing access only to authorized users that are eligible for accessing or modifying the data.

There are several ways to secure your endpoints. Of course, the most trivial one is the so called, “Basic Auth”, where you would require the user to pass his username and password through request headers.

For APIs dealing with sensitive data more complex security methods may apply. For example, a user can be required to have a PFX certificate installed on the machine from which he is calling the endpoints and passing it among the request. Though, the most common way of securing APIs is either by requiring the user to pass an “API Key” or a “Bearer Token” through the request headers or as a query parameter every time he makes a call.

A discussion can start here about how the user is obtaining this key or token. Both are generated based on some sort of credentials and it’s your responsibility to decide how the users will obtain access to your API. The difference between them is the fact that the key is generated one time having a long lifetime, whereas the token needs to be re-generated depending of its time span.

When thinking about security, always have in mind your target users, put in the back of your mind how your users will use the API, how they will obtain this keys and try to make the authentication flow as easier as possible for them.

Architecture 🚧

Software design is definitely a huge, broad and debated topic among software architects, software experts, software consultants, tech evangelists or you name it. From my point of view, whatever you are building, your architecture should be low coupled, extensible and testable.

Probably you’ve heard about coupling and cohesion in software development before, but I want to stress out the importance of having a “low coupling and high cohesion” system. What this even means? Low coupling — it refers that modules that contain your application should not depend on each other at all or it should depend as low as possible and contrary of that, high cohesion — refers to the fact that elements inside a module should be tight connected and related to the scope of that module. This two keys of building a software will hugely improve the extensibility of the project and it’s life span.

Why your API should be extensible? I had the chance to work on some long lived applications, started years ago when probably people didn’t thought how fast technology will evolve and change. Moreover, probably the information about software programming was little to none and everybody assumed that things won’t change. Having said that, I saw how those systems were so rough and hard to work with, so tight together that you would have to modify in tons of places to get some feature and I cannot point out enough how hard was to debug the code. That probably are some of the reasons why many big companies started to re-write their old software. But now, we do have a lot of information out there and we are aware that things are gonna change, and they’re gonna change fast, so always think of an architecture that is quickly extensible to whatever needs your project might have in the future.

Testable. Yes you need testing and yes your architecture dictates how easy you’re gonna incorporate testing in your application. If you do not isolate the components of the application, if you don’t follow the single responsibility principle, you’ll find yourself having to write a lot of code to be able to do unit testing or even worse you won’t be able to do that and you will need to resume to only having integration tests.

Testing 🔍

You need to have testing in mind when building an API because probably along the way your team will increase, many people will work together on different parts of the application and things will change fast, but can also break even faster. Consider having as many unit tests as possible, but don’t forget about integration tests as well. Always run your tests on your CI/CD pipeline. In the long run, having unit and integration tests for your API will facilitate its stability and solidness.

Logging ✏️

Do I really need to point this out? I think if you count the number of hours developers spent investigating an issue due to lack of logging or bad logging it will look something like this ➿. Yes, there is enormous time spent investigating issues where there is no logging. This is a must and needs to be done right. Try catching exceptions at application level like unexpected errors, but also log expected and well defined errors and, of course, any bit of relevant information that would help you in a difficult situation. In dark times, a good log is gold, trust me.

Documenting 📝

How will you let people know how to call your API if you don’t have a solid documentation? Probably you will find some answers to that, but from my point of view any application should be very well documented. There are plenty of ways to do it. One would be by simply having a word document written about each endpoint. Though, I would suggest that you build an interactive interface documentation for your API. Something that when your users throws the API link into the browser they can see all the endpoints, information about them, information about how to authenticate and the possibility to directly call them. One very popular library for doing this is Swagger.

Versioning 🔂

As I’ve said above over the time your application might change, might have different needs and might behave in a different way over the time. Why I cannot just change the existing code? If you think long term and if you think being successful you’ll probably have a lot of clients for your API. Let’s say that you have a new client that is waiting for you to deploy a new breaking change version at a specific date. Existing clients will need to change something on their end to support this new API version, but they cannot align with your timeline or they do not want to spend time changing to the new version even if it has more features. That’s where versioning comes into place, your existing clients will still use the old version without any impact and you are able to deploy the breaking change code to your new client on a new version route.

Caching 📂

Most often you will have some part of your data that is not changing to often ,but might be required for most of the requests, you need it for some checks or any other twist and tricks you need for your application. I suggest you think about that from the beginning and build an infrastructure for caching. You can choose from in memory application caching, database caching or other caching provider out there. Note, that your application might end up being in a load balancer served by multiple instances, so probably you should think about distributed caching from the beginning.

Final thoughts We went in detail about seven key components I suggest you think about when you plan to develop your brand new API. I want to outline that I’m just expressing my point of view about building an API at the moment of writing this article. There are plenty of other suggestions out there that are also good and probably different. Feel free to reach my on any social platform or in comments for questions or suggestions.

In my next article I plan to illustrate step by step how to build an API in .NET Core 3.1 based on this article. We will use Identity Server 4 for securing our API, we will build on a clean architecture, do unit tests, use versioning, use Nlog databse logging, configure swagger for interactive online documentation and use Redis for distribute caching. Stay tuned!