Designing an API 🤖

‍Have you ever thought about how an application communicates with a remote server, or another application? What happens when you like someone's picture on Instagram or when you send an instant message? All the happenings behind all these functions are called Application Programming Interfaces or APIs.

What are APi's:

Simply put, an Application Programming Interface is a software intermediary that allows two applications to talk to each other.

For example, Instagram’s API (while not public), introduces features for liking a picture, leaving a comment. These are functions that get introduced and can be directly utilized once installing the API. It’s what allows the communication between your actions and the server.

Most of the time, an API comes in the form of a module that can be imported, this introduces a bunch of new functions in your code that will allow you to communicate directly with another application. An API is a link between you and a server, it’s a flow of information that translates your actions into server-understandable commands.

Imagine you’re sitting at a restaurant, you order food, that order gets sent to the kitchen, once your food is ready it comes back to you. The server is the API, the link between you, and the distant kitchen or server. The waiter writes down the ordered dish and the quantity so that the cooks can understand what they have to deliver.

Note that in our example, the server serves two functions, it delivers information to the server, but can also deliver stuff to you. This could well be a function called number_of_likes in your API that tells you how many likes a picture has.

Why you'd want to develop one:

As a company or service provider, you might want to develop an easy, secure, and controlled way to access your servers. This can be for employee use, clients use, or even third party, it allows you to limit the interactions with your server and protect yourself from random people running code and potential malware on your service while making yourself indispensable.

Here are a few reasons why you should think about an API:

• Security
• Reaching more people
• Heavily invested customers
• Efficiency
• Code quality

By limiting the options inside your API, you control what happens on the server and the information it’s receiving. By standardizing everything, it becomes much easier to treat that information, understand the different errors and where there might be a problem.

Having an API also means you can make it public if you’ve made it reliable, feature-filled, and performant, users should flock to you.  Reaching more users and getting them invested in your API means they start relying on it. Redesigning the whole thing would be costly for them, you make their life easier by maintaining part of their code. This means you can charge a certain fee for your service.

By running your API, you can implement ways of analyzing the ongoing traffic, this helps you understand what is resource-intensive, where you can make improvements and what has to be redesigned.

Lastly, thinking in terms of API makes your code clearer, it dissects the different steps that happen and allows for easy debugging. This allows for clarity and helps others understand what your program does, even if they have not written the code.

How you can build your own:

Here’s a list of ideas to keep in mind when building your API:

• Security
• Understandable
• Document and document even further
• Don’t mention the implementation
• Start small with a few features
• Look for feedback and gather requirements

To ensure security and prevent the execution of remote code or malware, your API has to be tested, the goal is to limit the user to protect your server but also allow for interactions to make that API useful.  An API also has to be regularly maintained and documented. To ensure security, try and standardize your results, limit user input, and aim to use industry standards.

You’re building an API for someone else, someone that doesn’t know how your server works, your API has to be intuitive, try to name your functions accordingly, add comments, provide examples, etc… The goal is to document as much as possible to give clarity. With this in mind, you should absolutely not mention the implementation when documenting your API. Detailing the implementation gives ways of exploiting your system and compromises security. It also prevents you from changing that implementation further down the line for performance reasons.

Keep in mind when building your API that you can easily add features but can’t really remove them as users might have started developing on them. This means that you have to start off with minimal features, ensuring these are the most important and necessary ones that will truly help your users.

Once these basic functionalities are in place and working, try to get feedback. Is it really useful ?, What would users want next ? These questions will be most important and guide you to build your API.

Last but not least, it’s always a good idea to use well-known languages, HTTP and REST for example have kind of become the standard in the industry as most all API developers know their ins and outs. This helps once more to bring clarity while keeping the user in mind.

‍Creating an API means setting the rules and designing a playground for developers to interact with your server and the services you provide. As the creator, you have to set rules, on one side these have to ensure security by limiting the user’s possibilities, on the other you have to provide what will actually serve them and what they need, to keep your API relevant. Achieving this means creating loyal and dependant clients who truly gain something by using your API. Keep in mind, once up and running the API has to be maintained and documented. Analyzing the interactions between your users and the server can greatly improve efficiency as a result.