Why OpenAPI Matters

Ever since the Internet was created, the problem of connecting available services with consumers who need those services has been ubiquitous. Developers knew that “surely someone must have solved this problem, but where do I find their solution?”

An important development was the invention of APIs (Application Programming Interfaces). APIs enable an outside application to utilize the services a company creates via an HTTP (or other Internet protocol) request, which generates input into the company’s analysis engine. The analysis engine then creates a response that provides the informational result to the requesting agent.

Historic API Non-Standardization

If the developers found an online entitiy that provided the needed result, accessing the needed information required a specific calling protocol, and the returned response result had to be decoded. Figuring out how to structure the request for the information and how to decode the result required immense effort.

The development of REST APIs, JSON, etc. helped mitigate this problem. Still, integrating information from a new API into a new application involved tedious software engineering specific to the API that was being called.

The OpenAPI Methodology

The OpenAPI Initiative addresses this problem. The OpenAPI Specification explains the details. In essence, OpenAPI provides a uniformly formatted index that characterizes APIs. Within a consistent format, each API that has an OpenAPI document is described in a way that is both machine-readable and human-readable.

This enables programmers to search the catalog of APIs that have OpenAPI documents, and more easily find an API that may provide the information service they are seeking. No one wants to “reinvent the wheel.” If someone’s invented it, and they’re offering it for use by other developers via an OpenAPI document, it can be found far more easily than ever before. This makes the process of developing new products that depend on APIs significantly more efficient. The search for what you need as a developer is easier, and interfacing with the needed API is described in detail in the OpenAPI document; hence, the developer doesn’t need to spend time tediously decoding the often-minimal API descriptions that individual companies provide.

The OpenAPI specification

defines a standard, programming language-agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

Advantages of Using OpenAPI

If your company has an API wherein you seek outside users, creating an OpenAPI document that describes your API makes a lot of sense. Developers will create software that can search any OpenAPI document. Your OpenAPI document becomes a searchable item in a catalog of a multitude of available APIs. If the only way to discover the characteristics of your API is to go to your company’s site and search through the site to find out what your API provides, how it must be accessed, and how the results must be decoded — that’s too much work for a potential customer if your competitor has an easily searchable OpenAPI document available.

Conclusion

The OpenAPI Initiative is a major development in the advance of collaboration between diverse software developers. One team develops a product that receives an input and provides an output. Another team needs that output. A published OpenAPI document provides the second team with an easy structurally consistent way to understand how to request that information and decode the output.

This is new. And it’s important.

–Kevin Farnham