What is a good API?

API is the most powerful and useful concept in the computer world.

You can find API in the wide range of computer branches(such as web apps, operating systems, remote APIs). An application programming interface (API) is a way for two or more computer programs or components to communicate with each other. It is a type of software interface, offering a service to other pieces of software.

So API can help us to make and design better software and systems.

Be clear

Use logical and clear name for your API components: The names should be short and at the same time express the behavior of that components.

For example: example.com/prod/....

In this path, programmer want to show path of products, but is not clear. Is this prodded? or prodigality? or products?. So use clear syntax for resources, collections, and path names.

Good example1: example.com/products/123/....
Good example2: example.com/product/123/....

Good example 1 is good for products list. And good example 2 is good for using for one product.

Use clear comment for each piece of your code: Others should understand your code,or nor, you shouldn't understand your own code first?! Sometime you want to back to your codes and make some change or review it; comment help you for understanding what you did and every pieces of code has what behavior and how does it work.

Make response (error or success) messages useful

One of the most important part of each API is response per request.

The API response structure should be consistent and easy to understand. It should include a status code, a message, and the actual data being returned. The message should provide a brief explanation of the status code, and the data should be in a well-defined format, such as JSON, Protobuf, XML, GraphQL.

When creating a response object, it is wise only to return what the external user will need because building a large microservice will affect the performance and more.

When you're returning an error message when an external user queries the database, the message should be clear and concise – not just a generic error message like "Error Found" or "Error occurred."

This should be the title of the response, and the data or subject section should explain what sort of error occurred.

This is my personal take when creating an API error message. Do not return an unnecessary error message. Let's say some user data has a maximum character length of 5, and an external user queries the API for user data with a character length of 8.

Just message is not enough

Use message and error code

This method can make our API flexible. This codes can be use in other sides of system.

Don't Create Side Effects on the API

A side effect is, for example, when an external user queries an API for the user's first name but it returns the ID and full name.

When creating an API, try not to define everything in one function as much as possible. If the API sets many flags or does many tasks simultaneously, it should be split into multiple APIs. That's where atomicity comes to play.

Atomicity is when multiple operations are grouped into a single logical entity. Atomicity is important when creating an API. When using atomicity, poorly naming a function is just a terrible idea.

Stability

Consistency in APIs means no change in API behavior and performance over time. This is very important for developers because it gives them the confidence that their applications will work continuously and without problems.

There are several types of constants in APIs:

1. Behavioral stability:

This type of consistency ensures that the API always behaves the same way, regardless of what changes have occurred in the API's internal infrastructure.

For example, if a particular endpoint returns a JSON object with a certain structure, this structure should always remain constant.

1. Data consistency:

This type of consistency ensures that the data returned by the API is always accurate and consistent.

For example, if a particular endpoint returns information about a product, this information must always be up-to-date and correct.

1. Version stability:

• This type of consistency ensures that different versions of the API are compatible with each other.

• For example, if an API releases a new version, this version must work with applications that use previous versions of the API.

Principles of transactions

If you have worked with databases, you know that transactions must have certain characteristics in order to ensure their correctness.

It is better to refer to the database system design book to know these systems.

At The End

Designing a good API is like building a bridge.

A good bridge:

Makes it easy to cross, Is strong and reliable, Can handle a lot of traffic, Is secure

To build a good bridge:

• You need to know the purpose of the bridge
• You need to consider the needs of the people who will be using it
• You need to design a clear path to follow
• You need to use the right materials
• You need to put up clear warning signs
• You need to provide a complete and up-to-date map and guide
• You need to test the bridge thoroughly
• You need to protect your bridge from damage

By taking the time to design your API properly, you can create a valuable and efficient tool that will help you achieve your goals.