Top 6 Common Mistakes to Avoid When Building an API

Hello and welcome to today’s episode of “What makes an API tick?” where we will be talking about what makes an API shine and what are their most commonly encountered design mistakes.

When using or building an API, developers must ask themselves a few questions first. Is it consistent? Will it share too many things? Is the error handling done properly? If you want to know the answer to these questions, come along and find out for yourself!

Why APIs are important
Common API design mistakes you need to avoid
Inconsistency
Lack of Data Validation
Data Oversharing
Unclear Error Codes
Incorrect Usage of HTTP Methods
Lack of Attention to Scalability
Summing it all up

Why APIs are important

As you might already know, API stands for Application Programming Interface, which is a software-to-software interface that connects two separate applications and enables exchanging data between them.

Communication is very important, even between applications! For example, if you wish to implement face recognition within your project, it would end up being quite a challenging task and, naturally, take up a lot of your time. Consider using an API to speed up the process. This way, you wouldn’t be required to write too much code either!

The same goes if you wish to add maps to your application. Wouldn’t it be easier to use the Google Maps API rather than creating it on your own?

You want to build your API, so let’s see what mistakes to avoid so we end up with a healthy and efficient service.

Common API design mistakes you need to avoid

Inconsistency

Can the inconsistency of one’s code influence the performance of an API? Well, of course it can! Nicely written code is easier to understand and interpret, while inconsistent code can give you a hard time later on.

For instance, if you would be new to the job of working on an API, the time it would take you to understand its functionalities depends on how the code is written. Naming conventions are a good example, as sticking with a single format can make coding more intuitive and easier to understand.

Using a chaotic URL structure can also be harmful. Let’s see an example.

https://api.someapi.com/v3/getanswers/user_questions/userAnswers/sv5ncRhbhjMa21iR

We can both agree that the URL presented above is hard to read and could be difficult to use for testing. Wouldn’t it be more convenient to avoid mixing camelCaseing with using an underscore like this?

https://api.someapi.com/v3/getAnswers/userQuestions/userAnswers/sv5ncRhbhjMa21iR

Lack of Data Validation

Validating incoming data before anything else is an essential matter, as it can damage your project (and vacation plans) if it is not done correctly.

Some things may seem straightforward to you, but somebody else might mess things up and find a crack in your system.

Input validation can be critical for your database. For example, obligatory fields cannot be empty, and some values need to respect a particular format, like having at least one special character, and so on.

Make sure to validate your data before sending it off!

Data Oversharing

Oversharing data can be a time-saver at that moment, but in the long term, it can create even more problems. If you need to send some information of an object as a response, you might be tempted to send the entire object instead of just the needed properties.

Let’s say your API needs to send information regarding a hotel: its name, address, and why not, the reception’s phone number. The database was generous and using a single query, it gave more information for you to process, and the object looks like this:

{
“id”: “007”,
“name”: “Grand Sample Hotel”,
“address”: “Sample Street no. 34”,
“phone”: “(555) 555–1234”,
“stars”: 4,
“rooms”: 50,
“employees”: 89,
“coordinates”: {
“lat”: 30,
“long”: 30
},
“image”: “https://sample.com/sample”,
“updated”: “01/01/2021”
}

Now, you could send the entire object, or just the properties requested from the API.

How could this ever become a problem you ask? Well, if the client will use the extra information you provided, you would need to support the fields forever. Let’s say that in the future you’d like to separate some fields into different tables, but you still have to provide the hotel information as you did before, which means you need to use different queries for your database to extract the necessary information and send it in the same format too.

A good practice is to only send the information needed by the user. This concept is commonly used in programming that it even got a name attached: You Aren’t Gonna Need It.

Why give something away when it’s not asked for?

Unclear Error Codes

We all know how frustrating it can be when getting a “Something went wrong” error message from an API. Poorly handled errors can slow the development process and waste your time answering a high number of support tickets.

If the API handles errors with clear messages and HTTP status codes, it will definitely help the user solve the problem at hand, and the API will be more reliable and, thus, used more efficiently. Here is a list of status codes for you to choose from.

Take note that if an API returns 200 status code, it doesn’t always mean that we got the information we wanted, but include the error in the response data instead.

Incorrect Usage of HTTP Methods

Even though it is common knowledge what each HTTP Method is used for, mistakes can still be made, even among advanced-level developers. GET, PUT, POST, PATCH, and DELETE are some of the most used methods, each having its own role.

For example, you should use the GET method in order to retrieve data, while the POST method is used in order to submit an entity to a specific resource.

Mixing up HTTP Methods can also be the result of poorly written documentation, which doesn’t necessarily specify which method to use. Assuming which methods to use based on previously used APIs can also be the problem, as some services use the POST method to create resources and the PUT method to modify them, while others use the POST method to handle both cases.

Lack of Attention to Scalability

When building something, it is good practice to view the bigger picture and prepare beforehand, instead of tying your hands behind your back later on. Scalability issues could have a huge impact on the API, as getting more users may affect its performance and this may scare potential customers off.

Choosing a database and a web server that can scale as the API grows is the right option, even though you might not need those features from the beginning.

Summing it all up

I hope this article made it clear that building an API isn’t as easy as it sounds and that you need to take a few things into account before starting the whole development process.

Think about how an API should be from your perspective. It should communicate efficiently with the user, be easy to understand and to use, send only the needed information, and of course, be scalable as time passes and more people use the API.

The team at WebScrapingAPI did an excellent job of building an efficient API. Take a look at the documentation and draw your own conclusion.