APIs have been around for a really long time connecting different logical units together but they were not meant to be used by a lot of people in the past. Nowadays, APIs are not constrained to the Backend side of applications anymore and are more consumer-driven.
The universe of APIs is regularly one of contending standards, interests, and arrangements. Standards help give a common framework of communication and development and ground us in picking the correct tools dependent on a particular need.
What is OpenAPI?
I really like the explanation from OpenAPI website: "The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.".[1]
Summarizing, OpenAPI Specification is a solution that produces machine-readable documentation for REST APIs.
Developing APIs based on OpenAPI spec
As Test-driven development (TDD) that combines test-first development where you write a test before you write a solution code to fulfill that test and refactor it, we can also specify endpoints of an API using the OpenAPI framework before starting coding them and refactor. So, prior to beginning to build the business logic of an API, test it, or any other lifecycle, we create the API's interface, specifying the accurate requests and responses endpoints will display.
Why OpenAPI spec-driven development?
A significant advantage of developing APIs based on OpenAPI specifications is that it enables independence between teams, e.g, Frontend, Backend and QA Engineers know how the API is supposed to do, so they are all aligned on it. Removing these dependencies will also speed up the release process because different teams can do their tasks at a much faster pace.
Another advantage of using this approach is the improvement of Developer experience. Developer experience is about delivering robust functionality that is stable, speedy, and visually intuitive.[2] If you're thinking about how it can improve the developer experience, you just need to remember that developers will consume your API and having a well defined/documented API will have a great impact on it. You can focus on the API consumer's needs beforehand.
Conclusion
As I said at the beginning APIs were not meant to be used by a lot of people in the past but nowadays, they are not limited to the Backend side of applications anymore and are more consumer-driven. So, we need people to comprehend what APIs do, which is the reason a consumer-driven perspective on APIs is quick getting on and the OpenAPI Specification helps us to build APIs while guaranteeing a good developer experience through a definition driven methodology.
Reference
1 - https://swagger.io/specification/
2 - https://hackernoon.com/developer-experience-dx-devs-are-people-too-6590d6577afe
Top comments (0)