The universe of APIs is regularly one of competing 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 the 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, the 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
APIs have evolved beyond a typical backend to frontend pattern. So evolving a standard to help explain an API is more important then ever, which is the reason a consumer-driven perspective on APIs is quickly spreading 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)