What is OpenAPI?

The OpenAPI specification (OAS) is a standard used to describe APIs. OAS is programming language independent. The standard is easy to interpret and understand by humans and computers. We define OpenAPI-compliant APIs in YAML or JSON.

In the further part of the article, I will refer to the OpenAPI standard in version 3.0.3 (https://spec.openapis.org/oas/v3.0.3) . The latest version can be found on the OpenAPI standard website (https://www.openapis.org/) .

The OpenAPI specification defines the structure of the objects, their type, description or requiredness. According to the OpenAPI specification, the minimum API is

Let's look at the specification to analyze how to read it.

In the specification https://spec.openapis.org/oas/v3.0.3 we can find the definition of the main OpenAPI Object.

The required fields are:

• openapi, which is a string type
• info, type Info
• paths, type Paths

So, let's analyze the definition of the Info object.

The required fields are:

• title, type string
• version, type string

Let's look at the definition of Paths.

As described Paths can be empty.

Thus, the minimum form of the API definition according to the OpenAPI standard has the form

Designing an API by manual analysis of the specification is time-consuming, so it is worth using one of the tools that prompts the syntax, validates the correctness of the prepared document, and visualizes the designed API.

The most popular tool for this is Swagger.

What is Swagger used for?

Swagger (https://swagger.io/) is a set of tools to help you design, implement, test and document your API.

It consists of tools such as:

• Swagger Editor – a tool that facilitates API design in accordance with OpenAPI
• Swagger UI – a tool that presents the designed API
• Swagger Codegen – a tool that generates client and server code based on the designed API
• Swagger Hub – a platform for designing and documenting APIs for teams and companies

Let's design the first API in Swagger Editor (https://editor.swagger.io/) .

In the Swagger Editor tool, on the left, we see the API project in YAML (we can also use JSON), and on the right, the visualization in Swagger UI.

Now let's design more complicated OpenAPI compliant APIs.

API project for the Customer's domain

Together, we will design an API for the Customer's domain in a sample store.

The API will enable:

• getting the list of customers
• getting details of a specific customer
• adding a customer
• modifying a customer
• deleting a customer

For this purpose, we will design the customers resource.

• /v1/customers – it will allow to get a list of customers and create a new customer
• /v1/customers/{customerId} – it will allow to get details of a specific customer, update customer and delete customer

We will use HTTP operations GET to fetch, POST to create, PUT to update and DELETE to delete resources.

The resource designed in this way must be placed in the paths section according to OpenAPI.

In the next step, let's design a communication data model that we will use in the API.

Let the customer be defined by the attributes first name, last name, email address and customer address, where only the customer address is not required. The address consists of the street, apartment number, city, postal code, and country. Additionally, let's introduce a customer list object.

Now let's design the customer, address, and customer list objects according to OpenAPI in the components section.

In our solution, we will apply a simplification. When we are getting a list of customers, there can be a lot of data. A popular solution to improve performance is the use a paging of results. In our example, we do not introduce paging.

In the next step, we will design the details of the previously introduced operations.

Let's start with the operation of getting the list of customers. To retrieve a list of all customers, we do not need to pass any parameters in the request.

We have defined possible response codes for the operation: 200, 400, 401, 500 and 503 according to the HTTP protocol. For code 200, a list of customers will be returned. In other cases, the code with information about the error.

When we use the Swagger Editor, the visualization of the designed resource is visible on the right.

In the next step, we will design the operation of creating a new customer. In this case, we need to pass the details of the customer to be created in the request.

In response, we will receive the code 201, 400, 401, 500 or 503. For the 201 code, which will inform about the correct creation of the client, we will additionally provide the location of the created resource in the response in the headers section.

Next, let's move on to design the getting of customer details. In this case, we will enter the customerId parameter that will be passed in the URL path. If successful, the customer details will be returned with a 200 HTTP code.

The next step is to design the customer data update operation. For this we will use the PUT operation. In the request, we must provide details of the updated client, and in the URL path, the customer id (customerId).

In response, we will receive a code informing about the status of the operation: 200, 400, 401, 404, 500 or 503.

To enable the deletion of the customer, we will use the DELETE operation. We need to pass the id of the customer we want to delete. As for customer fetching and customer updating operations, we must pass the customerId in the URL path.

Only a response code of 200, 400, 401, 404, 500 or 503 will be returned for a customer delete operation.

We will use JWT tokens in our API to ensure security. We will set the authorization globally for all resources. For this purpose, we will add the definition of the JwtAuthToken object in the components section and complete the security section.

The API prepared by us in the Swagger tool is presented in the figure below.

You can also download the designed API by clicking on the LINK .

Thank you for reading the article. If you would like to share your comment with me, write to me at marcin@marcinziemek.com

If you want to develop your knowledge of IT systems integration design, check out my book available at: https://integration.marcinziemek.com