When linting an OpenAPI document (or any other JSON or YAML document with Spectral), the hardest part is ensuring you’re not missing your target and so be sure that expected checks will be done. In this post, we’ll see how to be sure a Spectral rule will be triggered when checking the presence of an element.

As API governance often rhymes with “policy enforcement,” API contract linting can be seen as the panacea of API governance: it can be used to ensure API contracts conform to pre-defined rules. But both API linting and API governance are more than that. Let’s discover the contributions and limitations of API contract linting in API governance.

Adding a prefix to a name should be carefully weighed because it impacts the overall design of an API, some code, or a specification and its usability for humans and machines. The discussion related to apiResponses, pathResponses, and responses properties in the early design of OpenAPI v4 is a perfect example of that concern.

API governance means policies, institutions, processes, and indicators. But without the alignment, enablement, collaboration, and guidance values in mind, API governance can quickly become a senseless, kafkaesque, and counter-productive API dictatorship, which will slowly but surely kill the organization, or its APIs at the least. 

After formally defining API governance relative to IT governance, corporate governance, and governance, let’s dive deeper and describe the four components of API governance: policies, institutions, processes, and indicators.

Let’s compare versions Swagger 2.0 and OpenAPI 3.0, and 3.1 to demonstrate the benefits of the new features introduced by 3.x versions to create more precise, better documented, more practical, and future-proof API contract descriptions.

In the collective unconscious, API governance often rhymes with API police. Reducing API governance to the need for order caused by the chaos of an organization’s myriad APIs is too reductive, and it risks not looking at the problem at hand from the right angle. Why not define API governance relatively to IT governance, corporate governance, and governance to better understand what it is?

The info property of an OpenAPI document contains metadata that provides an overview of an API, but what does it represent exactly? How did it evolve across the OpenAPI Specification versions? And how to can it be used and misused? This is the second post in the OpenAPI Specification Reference series.

No OpenAPI document without the openapi property, but what does it represent? How did it evolve across the OpenAPI Specification versions? And how to take advantage of it? This is the first post in the OpenAPI Specification Reference series.

Are you struggling to design consistent APIs? On the verge of losing sanity while checking every single property of every schema is camelCased? Never remembering the parameters to use for pagination? Spectral is the tool you need: it will lint JSON Schema, AsyncAPI, and OpenAPI documents and do those checks for you.