The Benefits of OpenAPI-Driven API Development

  March 15, 2018

As industries mature, standards are bound to appear to allow for better engineering and usage.

This has been the case from time immemorial. Be it the geometrical intricacy in Roman canals, the triangular symmetry in Egyptian pyramids, or the spatial harmony in Indian monasteries, standards and specifications have helped engineers set unique rules for sustainable engineering.

Standards help provide a common framework of communication and development, and ground us in picking the right tools based on a specific need.

The standard for API definition in the RESTful API world is the OpenAPI Specification (OAS).

The OAS, which is based on the original "Swagger Specification," has picked up tremendous traction in API development, and we’re seeing adoption by tens of thousands of API developers and consumers.

But why now? Why is the world suddenly embracing a standard specification for the RESTful architecture, when just a few years ago, REST aficionados were almost completely against a specification to define REST?

The New Age Of REST APIs

APIs are no longer confined to the back end of your applications. APIs have been around long before the advent of the PC, connecting different logical units together.

In the past, APIs were not meant to be used by a lot of people. APIs were data driven, and were meant to solve a few special use cases of connection and communication. Documentation was minimal, if any, and the canonicals used followed jargon directly from the core database, meaning no one outside a small network of people could understand them.

Needless to say, APIs of the past weren’t meant for self-service consumption.

The above no longer applies to the modern web API. We are in a new age where APIs are not just allowing business to build and scale faster, but are also driving strategic and business targets through integrations and consumption of third party services for shared revenue and growth. The new age of REST APIs, unlike their predecessors, are not data driven, but more consumer driven.

Well-designed APIs that solve a real consumer problem is the name of the game, and we’re seeing this focus in APIs from companies like Dropbox, Stripe and eBay. Reusable interfaces based on HTTP standards are now required by a lot of companies that allow for reuse of data and functions, built for consumer demand and self-service

Enter the OpenAPI Specification (OAS)

The OAS is to REST what WSDL was to SOAP. It provides a common framework of designers, developers, testers, and devops to build and maintain APIs. Think of the specification as a set of rules to build and implement a REST API. The OAS is language agnostic, and is both human and machine readable, which allows both people and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic.

So, we know the OAS can help you in building consumer-centric APIs, but how best can you use the specification in your development lifecycle?

OpenAPI-Driven API Development

Definition driven API development advocates for designing the API's definition first before any other lifecycle operation has been implemented. This means even before you start building the API's business logic, before you test the API for any errors or defects, or any other lifecycle function, you will design the API's interface, detailing the exact requests and responses your API end points will showcase.

Benefits of an OAS-Driven Approach

The definition-driven approach brings with it some great benefits that directly relate to a consumer-centric approach to API development.

  • Better Developer Experience (DX): DX is the aggregate of all the experiences a developer may experience, both positive and negative, when consuming and integrating with your software. Good developer experience for API consumption is critical in a hyper competitive API ecosystem. You can actually focus on the API consumer's needs beforehand. This allows you to have a developer-centric approach and ensure catering to if your end consumers in an optimal fashion before racing time and other aspects of the development.
  • Enables Independence: The approach reduced dependencies between different teams working on your API, like the front-end and back-end teams, or the architects, tech writers and QA. This is because the definition of the API keeps various stakeholders aligned on what the API is supposed to do, and how it relates to their job function. It acts as the contract between the API's intended service and its functionality, and ensures easier communication between them.
  • Faster go to market: Since dependencies are removed, different teams can actually perform their functions at a much faster and efficient rate. The hand-off process between teams is significantly easier, which makes for your APIs being released at a much faster rate.

Closing Notes

The modern API no longer complies with the traditional data-centric view of the world. Applications, both software and hardware, are all connected and APIs are at the center of this digital revolution. For these applications to connect, we need real human developers to understand what your API does, which is why a consumer-centric view of APIs is fast catching on.

The OpenAPI Specification helps you achieve APIs that solve a prospects needs while ensuring good developer experience through a definition driven approach.

You can watch this on-demand webinar on the definition driven approach to API development for now. In the coming months, I will be following up with more articles that explain in detail how an OAS definition can help in different API lifecycle functions like API design, documentation, testing and monitoring.