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. In an OpenAPI document, the description of the API located in the info section is not mandatory. A document without that information is syntactically valid. But from an API documentation perspective, that can be an issue. So let’s create a rule that will enforce providing this information ..read more

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. API linting and API governance Linting an API contract consists in analyzing its interface to “detect bugs, stylistic errors, and suspicious constructs” (like the original linting). That can be done, for instance, with a tool called Spectral to analyze O ..read more

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. The context Version 4 (aka. Moonwalk) of the OpenAPI Specification is in its early discussion stage. It breaks everything, and the direction taken is quite promising! This post takes its source in a discussion related to apiResponses, pathResponses, and responses properti ..read more

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.  This post’s banner is an illustration from the first page of the Encyclopédie (Encyclopedia or Reasoned Dictionary of Sciences, Arts and Crafts). API Governance definition I’m continuing my exploration of API governance definition. In my initial post, I attempt ..read more

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. This post banner is a part of the “Figurative system of human knowledge”, the structure that the Encyclopédie (Encyclopedia or Reasoned Dictionary of Sciences, Arts and Crafts) organised knowledge into. API governance definition In a previous post titled Attempting to define API governance, I described API governance as follows: API governance is establishing and overseei ..read more

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. OpenAPI Specification Reference Series This series aims to provide complete cross-version reference documentation about the OpenAPI Specification aggregating different sources of information. For each analyzed element, you’ll find its definition, how it evolved across the different versions of ..read more

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. OpenAPI Specification Reference Series This series aims to provide complete cross-version reference documentation about the OpenAPI Specification aggregating different sources of information. For each analyzed element, you’ll find its definition, how it evolved across the different versions of the specification, how it is used and misused and where to f ..read more

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. Banner by my partner in crime Mister Lapin. Spectral is a JSON and YAML linter Spectral is an open-source JSON and YAML linter created by Stoplight. Imagine ESLint or SonarQube but for JSON and YAML. Lint, or a linter, is a static code analysis tool used to flag programming errors ..read more

The OpenAPI Specification can facilitate everyone’s life and participate in the creation of better APIs and a better API ecosystem. But it will work only if the members of the OpenAPI-based tools club follow the rules. Banner by my partner in crime Mister Lapin. As an OpenAPI-based tool creator and Web API tool creator in general, you have a responsibility to promote the use of the OpenAPI specification, demonstrate how to take advantage of it, and educate the API community. Why? Because you’re a nice person/organization and you want to help everyone create the best possible APIs and API ecosy ..read more