OpenAPI Specification can be used to secure and accelerate the API lifecycle.

The API lifecycle is a topic of much discussion — and rightfully so. The API space is agile, ever changing, and its participants must continually meet the shifting kaleidoscope of user needs and demands.

Speeding up and securing this lifecycle is seen by many, then, to be the Holy Grail. Being able to leverage proven API specifications is a powerful method, as proper specification usage opens up a whole new realm for developers. Whether this be in efficient, automated documentation, improved usability and developer experience with dynamic sandboxing, or decreasing speed to market through faster iteration, the benefits can’t be overstated.

Today we’ll look at a wonderful solution to help reach this lofty goal: the OpenAPI Specification. We’ll talk a little bit about what it actually is, and how it can enable faster, more secure API development.

What is the OpenAPI Specification?

The OpenAPI Specification is a specification and framework implementation designed to create machine-readable interface files for describing, producing, consuming, and visualizing web services in a RESTful architecture. As Lauret describes, the use cases are numerous:

“The OpenAPI specification universe extends way beyond generated documentation. It’s boundless. The OpenAPI specification can be used to accelerate and secure API creation and evolution.”

Before there was OpenAPI, there was Swagger. Swagger was originally designed for use on the Wordnik word discovery service, a web service that was touted to “find meaning in words.” Swagger was then designed under this same guideline, though with a slight deviation — to “find meaning in APIs.”

In 2015, API provider SmartBear acquired the open-source Swagger framework, and began to expand it out of the confines of Wordnik’s use case. In 2015, SmartBear helped to create a new organization under the banner of the Linux Foundation called the Open API Initiative, working with Google, IBM, and Microsoft to craft new tools and solutions. As part of their efforts, they released the Swagger Specification to the group, dubbing it the OpenAPI Specification. It should be noted that that the tooling around the specification still retains the Swagger brand (Swagger Editor, UI, Codegen, etc). At the time of this writing, OpenAPI Specification is in a stable v2 with a version 3.0 in draft status.

Why OpenAPI Specification?

The OpenAPI specification has some really special features that make it so well-received in the API world. First and foremost, OpenAPI is language-agnostic. Unlike other solutions, this specification has no language preference and can work across any language with minor instruction.

Another huge benefit of the OpenAPI Specification is that, as a result of its specific dependence on declarative resource specification, clients have a much larger, more robust and holistic view of functionality. Instead of depending on restricted server code or documentation, the OpenAPI Specification, in many ways, describes itself.

Wrapped up into the OpenAPI Specification is the Swagger-Codegen, a piece of Swagger technology that utilizes a template-driven engine to generate documentation, server foundational stubs, and clients.

For many reasons, OpenAPI is often seen as the best solution to date for API development. With this in mind, how specifically does it help us toward our goal?

API Fastness

“API fastness is probably what every API provider aims to do — being able to deliver an API quickly but securely.”

Lauret defines API fastness as accelerating the development of an API and its resources while maintaining security and quality control. Essentially, you’re aiming for the best of both worlds, and as part of that, you’re accepting some limitations.

In the classic development lifecycle, you’re playing a game of balance — you sacrifice quality for speed to market, and you give up some speed when you focus on securing resources. Though not every project will have the same pitfalls, slow and methodical generally counters quick and innovative. As Mark Zuckerberg once said, “move fast and break things.”

Luckily, the OpenAPI Specification takes away a lot of the “break things” part of that motto and focuses more on the “move fast”. Here are 5 ways it does that.

1: Proper Design and Approach

Any good engineer can tell you that structures don’t fail because of the last brick, they fail because of the first. If you start with a shaky foundation, or bad bedrock, you’re going to collapse, and the same is true of an API.

The OpenAPI Specification provides perhaps one of the strongest foundations upon which one can build an API. It does this not by solely providing tools or approaches, but by providing a proper design approach towards how your API will be interacted with.

“A beginning is a very delicate time, especially for an API. Whether an API is internal or external, its design is crucial. A bad design can lead to a total disaster. It can kill projects and even companies.”

Perhaps the most powerful example of how the OpenAPI Specification does this is in the synchronization of source code and client libraries. Failing to synchronize these elements can result in divergent code sets and awful interactions for the consumer.

On the other hand, adopting a proper methodology for ensuring that content is properly synchronized can make for better functionality. The greatest part of all of this is that the three main ways this specification generation is done — Codegen, automatic generation (swagger-node-express and swagger-play), and manually — are completely adaptable to specific API functionalities and design aesthetics.

2: Complete Documentation and Description

SwaggerUI, an element of OpenAPI, is supremely powerful and capable when it comes to generating descriptive documentation. Due to where the OpenAPI Specification came from — specifically, Swagger — the main selling point of “accurate, easy documentation” that came with Swagger is also shared within OpenAPI. As Lauret describes:

“The OpenAPI specification is able to easily and efficiently describe an API. Every single aspect can be described easily in a simple but structured document.”

That’s not the end, either — the OpenAPI Specification is open by design, which has given rise to some serious contenders for functionality mirroring that of the SwaggerUI. For instance, APIs.guru have released their ReDoc solution as an alternative system.

That’s the real power here. Any documentation service worth its salt will get the job done, but the OpenAPI Specification is specifically built around the idea of opening up an API to multiple solutions, languages, and approaches in an effort to reach the best solution possible for any given permutation.

3: Rapid Testing and Iteration

The OpenAPI Specification utilizes a declarative resource specification, and as part of this, allows for easy exploration of the API without access to the server code or an understanding of the server implementation.

This means that, unlike other solutions where the dev has a great sandbox, but the average user is restricted, the API can be sandboxed in a way that allows for both developers and non-developers to understand and explore in an interactive sandbox.

This is all done via that magic implementation called the SwaggerUI. SwaggerUI reads the API description that is stated as part of the OpenAPI Specification, and renders it as a web-page.

While this is great from a consumer viewpoint, the real benefit here is in testing and iteration. By being able to actively test and modify API content during development in a sandboxed environment, endpoints can be tested against any permutation, resource access can be tested in a multitude of environments, and the API can be tested in interactions with other APIs.

This drastically aids in iteration, and enables truly rapid, dynamic testing with minimal overtime.

4: Shorter (More Secure) Time to Market

Due to the aforementioned drastic reduction in resource and time dedication for testing and iteration, this also naturally results in a decrease regarding time to market. By taking less time to iterate and using less resources between initial revisions, this results in a much quicker cycle as features are rolled into the main codeset dynamically.

A key sidenote here is that this also drastically increases the security level of the API. Because the developer is able to test and iterate with relative ease and quickness, issues in the code base and its interactions are discovered earlier in testing, and bugs are attached directly to stated resources.

Imagine building an engine. When putting the pieces together, you have to test each element, and upon the addition of a new part, you must test the engine as a whole. Now imagine the same situation, but with a super computer that allows each individual part to be tested no matter how deep the part is, how surrounded by other parts it is, and how core or ancillary to the overall functionality it is.

This is functionally what the OpenAPI Specification allows you to do — test anything dynamically and with low overhead and time between testing.

5: Machine and Human Readability and Translation

“The OpenAPI specification can also be used to create human-readable documentation.”

The OpenAPI Specification is a Rosetta Stone for the API space. Whereas other solutions generate machine-centric data for the purpose of functionality and then derive from this human readable documentation and specification (or vice versa), the OpenAPI specification starts from a different position — a progenitor language from which all other content is derived.

By functioning as a specification which describes the API, the OpenAPI Specification can then derive both machine and human readable content in a better, more complete way. This approach led Swagger to become a household name in the API space, and it continues to influence documentation trends to this day.

The OpenAPI Specification leverages its powers to create the most complete and useful content in both machine and human readable format; an important ability that simply cannot be overstated.

Conclusion: OpenAPI Enables an Agile API Lifecycle

As developers, API providers, and evangelists, the biggest issue we face in this industry is moving at a speed quick enough to iterate and innovate, while securing the resources our consumers depend on. It’s no easy task — many have tried and failed (and quite spectacularly so).

The OpenAPI Specification is possibly the best implementation at this moment for this exact purpose. Due to how it generates documentation, APIs from a description, and does so in such a dynamic, diverse way, the OpenAPI Specification bridges both worlds, enabling, as The API Handyman calls it, API fastness.