Generating Service Information

Generating service information is a critical prerequisite for exposing services to wider audiences. It not only helps Consumers understand and test service calls but also allows them to stay current with version changes in the service definitions.

It didn’t take long for the open-source community and software industry, in general, to standardize what service information should look like. In parallel, the tooling that helps generate this service information has evolved. Before looking at our tooling of choice, first, let’s understand the most commonly used API standard developed by the OpenAPI initiative.

OpenAPI specification

At the time of writing, the OpenAPI Specification v3.1.0 is the currently published version. The version number itself isn’t important to our learning, but rather what the OpenAPI specification is and what it hopes to achieve.

The following is taken from the beginning of the OpenAPI Specification, answering the question, “What is the OpenAPI Specification?”

Note: The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP 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 the guesswork in calling a service.

In short, this says we should conform to describing what a service is and how we can call it in a very standard way, regardless of who we are, whom we work for, what development language we use, or the audience our services may serve.

Thanks to the quick evolution of tooling to support this standard, we have two distinct approaches to conform with the OpenAPI standard:

1. Design an API by describing it as an OpenAPI standard and then generate code stubs for new services or compare the existing service code against it.

2. Code an API to meet our needs and then generate an OpenAPI Specification that describes it.

There’s plenty of tooling across most major development languages that support both approaches. The OpenAPI initiative recommends using a design-first approach as best practice. This would indicate that the tooling for describing an OpenAPI-compatible specification and then generating or testing against code is the best choice. However, we have to be aware that the tooling that supports reverse engineering the specification from existing code is still of great value. While we might design the API first and then generate new code or test existing code against it, the code is always at risk of change. So, having tooling that can generate the specification at runtime means we can always see as-is definitions. In effect, we want to statically align a desired API with actual code, but we also want to dynamically present the as-is API to any consumer at any given time, regardless of its alignment with a desired design.