Many questions have floated around my mind when I had to design from scratch a new Rest API. Where do I start? What is the best way to design an API? What tools do I need?

Nowadays APIs are fundamental parts of products around the world, to provide a connection between applications, to give access to our data and functionality. So you may think, how can I design a proper API that follows best practices and standards or that aligns to some kind of guide if there is any. Luckily Open API Specification (OAS) exists, which is the major standard to APIs design! 

Open API has a lot of advantages, and some of them are that it is language-agnostic, it provides a common frame for designers, developers and testers on how to create and easily maintain APIs avoiding common errors. 

Open API advantages

Open API has huge advantages and these are the most remarkable:

• It allows us to focus on the needs of the API consumer, abstracting from problems that may arise during the development
• It reduces dependency between teams working with the same API implementation.
• As well, implementation time is lower following Open API specification.
• There are a bunch of tools that allow developers to generate code and documentation from API design, as well as to validate its structure and test the final API.
• Open API files are easy to maintain and modify, with low impact on the product.
• On the internet there are amounts of examples to follow and here is the OAS website: https://spec.openapis.org/

Tools

Swagger is the most widely used tooling ecosystem for developing APIs with the OAS. We can find both open-source Swagger tools as well as professional tools.

Swagger provides a set of rules, specifications and tools that help us document our APIs easily, fast and with a format both machine-readable and human-readable. We can write a specification in YAML or JSON format.

I have used the free online editor: https://editor.swagger.io/

This tool is divided in two, on one side we have the editor, in YAML format, where we code the API spec, and on the other side the preview where we can see the final result and where errors are displayed if there were any.

There is a demo API Pet Store specification in which you can find the most used operations. Here you can find the complete specification for this example: https://petstore.swagger.io/?displayOperationId=false 

API design

Before doing anything, we first need to think about API design, analyzing business logic and thinking about possible errors. We need to start defining the API interface, request and responses. 

API definition

As we said before, we write the API specification in a YAML file.

I strongly suggest looking into the TM Forum Open API ecosystem portal examples before start.

https://projects.tmforum.org/wiki/display/API/TM+Forum+Ecosystem+API+Portal

There you can explore API solutions implemented for a variety of businesses and common and not-so-common applications.

TM Forum is an alliance of more than 850 global companies working together to break down technology and cultural barriers between digital service providers, technology suppliers, consultancies and systems integrators. So surely there you can obtain hi-class API definitions that can guide you to implement yours with great quality.

API implementation

Swagger also provides an open-source tool named Swagger Codegen that generates automatic code from an API YAML specification. You can generate server stubs or client SDKs instantly from your YAML file and in different languages like java, go, typescript, and many more.

API testing

It is really easy to test an API that follows Open API specifications. For this matter, we can use Swagger Inspector or SOAP UI.

Conclusion

To sum up, the advantages of following the OpenAPI standard in projects that involve API implementations are multiple. Open API allows us to detect possible failures in the early definition phase, boost the development and implementation process, execution of tests and easy documentation, emphasizing the cooperation of different teams involved, such as frontend, backend and QA. And, of course, what is essential, it allows us to finally offer our customers the delivery of a product that not only meets the standards but also meets their business needs.