APIs and How to design them — All you need to know !
Have you created a service and want others to use it? Well!!! Apis are the way to do it.
What is an API?
Suppose you have written a program that performs a task (maybe takes an input and returns an output based on it). You would want a way for other people to use your program — You need APIs for this purpose.
API stands for Application Programming Interface, which is a software interface between external users or other services and your program. We can expose API endpoints on the internet through which other applications can interact with our program.
Source: www.altexsoft.com
Designing good APIs
There’s no one right set of characteristics. Whatever design serves the purpose in an efficient manner is a “good API design”.
As a software developer, I would want the APIs to have the following set of characteristics which would ensure consistency, security, and efficiency in my system.
SRP (Single Responsibility Principle)
Source: LearnStuff.io
Ensure each API has a single responsibility. This makes the operation performed atomic and our database is consistent with what the clients expect. This way the client knows that if the API fails or returns an exception, then no part of the operation was performed. It reduces ambiguity.
Let’s take an example — Suppose we want to create a user and assign a label to it. If we use a single API to execute the operations and the API fails and returns an exception, there would be confusion whether the user was created and an exception occurred while creating the label, or exception was returned while creating the user and no user was created. So it is better to create 2 separate APIs, one for creating users and the other to update parameters/assign labels to users.
Naming the API
Name the APIs so that it becomes easy for the clients to guess the purpose of the API. The type of request (GET, PUT, POST, DELETE) adds context to the naming as well. This way if your server has a bunch of APIs exposed, it becomes easy for the client to manage the APIs while using them. Also, it makes debugging easier.
For example, if you want to get details of a user, you could name the API as
GET - /api/user/{userId}Similarly to delete the user you could name it as
DELETE — /api/user/{userId}Abstraction
Return only what is needed.
Sometimes you may be convinced to return extra information through your API maybe by apprehending certain requirements for the future. Trust me it’s not a good idea! (A lot of times it will happen that those requirements don’t come up or you will end up creating a separate API for it for some reason).
You don’t want to expose certain information which can be exploited by hackers to get into your system. Be careful!
Also exposing only what is needed is a neat way to present, creates less confusion, and also reduces coupling in some cases.
Returning less data — reduces response time and saves internet bandwidth. (And makes surfing easy for everyone!)
Logging
Logging API name, request parameters, response time is a good practice that helps to debug issues and maintain your program.
It is also important that you accidentally don’t log user sensitive information, like email, passwords, credit card details, etc. which may be received as part of the API request, and can be a probable security vulnerability.
Validate User Roles / Permissions
Add user role validations to APIs. It is obvious right!, you don’t want the regular users to have access to APIs meant for Admin.