5 Common Mistakes When Developing APIs | Dreamfactory

by Spencer Nguyen • October 11, 2021

An API essentially paly the role of a software intermediary that allows two applications to talk to each other. Every time you use an application like Facebook, send an instant message, or check the weather on your phone, you are using an API. The API is more than middleware however — it’s grown into an innovative business concept that can transform your business and digital strategy. When using APIs though, there are a variety of mistakes that developers can make. Read on to find out more on common mistakes when developing APIs and understand how to get it right from the start.

Common API Examples and API Technology

When you use an application on your cell phone, the application connects to the internet and sends data to a server. The server then retrieves this data, interprets it, performs the necessary actions, and sends it back to your phone. The application then interprets this data and presents you with the desired information in a readable way. That's what an API is — it's all done through the API.

Here's an example of a real API. You may be familiar with the process of searching for flights online. Just like with restaurants, you have a variety of options to choose from, including different cities, departure and return dates, etc. Let's say you book your flight on an airline's website. You choose a departure city and date, a return city and date, a cabin class, and other variables. In order to book your flight, you interact with the airline's website to access their database and see if seats are available on those dates and what the costs might be.

However, what if you don't use the airline's website, but a channel that has direct access to the information? What if you use an online travel service, such as Kayak or Expedia that aggregates information from a number of airline databases? The travel service, in this case, interacts with the airline's API. The API is the interface that, like your helpful server, can be requested by this online travel service to get information from the airline's database to book seats, baggage options, etc. The API then takes the airline's response to your request and properly delivers it back to the online travel service, which then shows you the most recent and relevant information.

1. Avoiding Limiting

API limiting allows you to control how an API grants access by defining permissions to validate specific API calls. It limits and controls what data a user can access via the API by defining temporary usage states.

As a developer, you can have several levels of limitation depending on the intended users. For example, you can restrict sensitive information about users under 18 while granting access to the same information to users 18 and older.

2. Stopping HTTP Method Overrides

The HTTP X-HTTP-Method-Override works as a custom header with a value of PUT or DELETE when calling your web API via JavaScript or via an XMLHttpRequest object from a web browser using an HTTP POST call. Since there are proxies, which only support POST and GET! methods, you can ask a proxies manager to call your web API. You can then ask a delegation manager to perform the appropriate actions.

3. Skipping Security Best Practices

You need to make sure your API is secure via authentication and other methods, but not at a high level, according to users who won't be satisfied with spending 5 minutes just to authenticate. Security must go hand in hand with usability! You can use token-based authentication and SSL/TLS for security and privacy.

Your API should communicate via secure channels with SSL certification. Defining users by role (administrator, viewer, editor, etc.) allows you to grant permissions accordingly and ensures you adhere to one of the most fundamental components of the API development process.

4. Poor Documentation for Your API

Creating proper documentation is important for both users and developers and is prevalent on any 'common mistakes when developing APIs' list. For developers, it allows them to better understand the whole process and users to check what exactly is available on your API.

Documentation should provide full details on endpoints, methods, requests and responses, possible responsive code case scenarios, and limitation limits — and can be published as a searchable web page for greater clarity.

5. Not Communicating With JSON

REST APIs work with JSON as the standard for data transfer. Unlike XML, which is not widely supported by frameworks, the majority of networked technologies use JSON.

JavaScript has built-in methods for encoding and decoding JSON via the Fetch API or another HTTP client. We also need to ensure that endpoints return JSON as a response. Avoid using verbs in endpoint paths; use nouns instead. You must use nouns that represent the entity at the endpoint path that we are retrieving or manipulating as a path, as having verbs in our API endpoint paths is not necessary.

The action must be specified by the HTTP request method we are performing. The most common methods include GET, POST, PUT, and DELETE. Where GET retrieves resources. POST submits new data to the server. PUT updates existing data. DELETE deletes data. The verbs correspond to CRUD operations. And so we should create routes like GET/articles/ to get news articles and POST/articles/ to add a new article, PUT/articles/:id to update the article with the given ID. DELETE/articles/:id is to delete an existing article with the given ID.

Developing a robust, scalable, and useful API doesn’t have to be complicated. If you follow a few extra steps and avoid these 10 API Developer Mistakes, you’ll minimize rework and create a full-featured API that provides tons of value. When you sign up for a free trial of DreamFactory, you’ll see firsthand how our no-code tools make building an API quick and easy.

Avoid API development mistakes with DreamFactory

To create successful APIs, developers must follow a set of best practices from design to implementation. In this article, we identified the top five common mistakes when developing APIs. DreamFactory is an API management platform that helps you streamline everything while you focus on building your frontend application. DreamFactory can help you bring your API-as-a-product mindset to life and get more out of the solutions your business is creating. Start your 14-day free trial today and experience it for yourself.