Best practices to design your first API Specification

Please note that this is not a technical tutorial. This is intended as a guide to see the best practices to create an API specification.

We would like to thank Aridam Kumar for their contribution to this developer tutorial.

In the previous tutorials, we’ve been mainly learning about the implementation stage of our development process. We learned:

1. How to build your first Hello Mule application
2. How to set up your global elements and properties files in Anypoint Studio
3. How to secure properties before deployment in Anypoint Studio
4. How to set up API Autodiscovery in Anypoint Studio
5. How to apply Client ID enforcement policy to your Mule app in API Manager

As you can see, the first four tutorials are mainly about Anypoint Studio, which is our IDE where we implement the code for our Mule app. We’ve also been using some Anypoint Platform products like Anypoint Runtime Manager, Anypoint API Manager, and Anypoint Exchange. But we haven’t learned how to create API Specifications yet. This tutorial will explain what an API is and why we need API Specifications. Later, we will dive in to create an API on our own.

What is an API?

An API is a type of technology that allows applications to talk to one another. APIs provide an easy and consistent way for developers to access data from backend systems, which helps secure the system and reduces complexity for developers that simply need some information from the backend system rather than the entire logic and database. The client sends a request for specific information or functionality to another system. That system returns the data or functionality in response. For example, when visiting a restaurant, customers do not go into the kitchen to get the food that they want. Instead, they place an order with a waiter who then goes into the kitchen and retrieves the items. APIs are the equivalent of the waiter, serving the information that a user requested.

What is an API Specification?

To send or receive data using an API, there is an expectation that it will be in a specific format that both sides can understand. That format is often very sensitive to the context(s) it serves. For example, when using an electrical appliance, the user knows that all wall sockets have a certain shape and provide electricity at 120 volts. These known guidelines essentially set an expectation for any device needing to be plugged into the wall. API specifications, written in the RESTful API Modeling Language (RAML) or Open API Specification (OAS) formats, provide the specific guidelines by which the API is built and communicates, just like an assembly guide and user manual.

Why are you building an API?

As a developer, you only want to have to build something once. When you build an application or integration, you want others to be able to build onto the work you’ve already done without having to modify the original code or spend hours creating custom code to fit within your current application.

The first step to building an API is to list out what your API needs to do. Do you have to send a text message, change a password, or edit a database entry? Once you identify what your API is going to accomplish, remember to design it with reusability in mind from the get-go. Since other developers are going to be consuming and accessing this API for years to come, you need to make sure that the initial contract (or API Specification) sets the ground rules of how the API should be interfaced. If you go and make changes to your contract later, it could break critical systems which could lead to downtime or other catastrophic results.

Creating an API Specification enables you to code around the API’s definition, rather than defining your API with code. With your API Specification, you can outline how you envision your API is supposed to operate, and then test it live in the browser while you are designing it. If you are using MuleSoft’s Anypoint Design Center, you can turn on the mocking service to try out your design live in the browser and identify major design-related issues before development starts.

API Specification’s components and best practices

API basics

Initially, the specification must clearly state the title of the API and the industry-standard that it will follow. You must also specify a base URI which is the URL in which your API is hosted, but this can be added later once the API is deployed to a hosting service. You can also choose to specify the communication protocol, such as HTTP, that your API will support.

Resources

If you are building a REST API, make sure to use nouns as resources instead of verbs. The reasoning behind this is that verbs don’t give you as much flexibility when you are designing your resources since they are tightly coupled to a specific action. When you use nouns, you can have loosely coupled resources that accomplish multiple tasks. For example, there would be no need to create the endpoint /getContacts when you could just name your resource /contacts and send a request against that resource. You could use this same resource to get a list of all the contacts, create a new contact, or delete all the contacts.

Additionally, it’s helpful to keep endpoints in the plural form. This helps to understand and avoid confusion when using the API. For example, the resource /contacts is self-explanatory because you know you’re acting upon the collection of contacts, as opposed to just one contact.

Methods

Each HTTP request method that you define should follow the correct verb logic. Here are the most popular methods and how they are most commonly used for.

For more information regarding the HTTP request methods, check out this documentation.

Query Parameters

When you are creating your endpoints and thinking about how users will consume with your APIs, there are a few best practices to follow when approaching your API design. Make sure to always use snake_case such as date_from or date_to.

Sorting can be a very expensive operation and it can lead to large costs down the road if not performed efficiently. If you are creating an API for this similar use case, you should offer a sorting operation such as a query parameter called sort or order_by where you can sort by specific fields like date_from. You can also offer a sort direction (ascending or descending) by defining an additional query parameter.

Filtering is another useful feature to control results or restrict them based on certain values. For example, you could implement a query parameter like city to find all records in that region. Pagination can list out results by batching the response for a certain number of entries at a time. You can set up query parameters such as page_size to list any number of entries per page, and page or page_number to navigate between pages.

Status Codes

Each HTTP response status code that you define should follow the defined standards. Here are the most popular status codes and what they mean.

For more information regarding the HTTP response status codes, check out this documentation.

Next Steps

There are other components that you can add to your API Specification like libraries, data types, security schemes, etc. We will be learning more about those in later tutorials. For now, you have a basic understanding of what is an API and an API Specification. In the next tutorial, we’ll learn how to actually create an API Specification in MuleSoft’s Anypoint Design Center.

Click on the Next button below to continue to the next tutorial.

Previous Next