Tag Archives: overlays

09 Jan
2025

Save edits to OpenAPI as an Overlay

For teams that generate OpenAPI from their codebase, there’s a tough choice between maintaining rich and extensive content such as Markdown descriptions and examples in codebase annotations, or in making those changes to the generated file – and then losing them when the code changes and the file is regenerated. The new OpenAPI Overlay Specification defines a format for storing updates to an OpenAPI document, and there’s a new generation of tools to make it easy to do, so let’s take a look. Continue reading →
12 Dec
2024

OpenAPI Overlays to avoid API oversharing

Most APIs aren’t perfect. By design they are long-lived and may serve many audiences. I see a lot of organisations maintaining multiple versions of APIs, or simply not documenting some of the endpoints to avoid them being included in the published documentation and confusing users. The problem of API redaction is a real one in most organisations, and it goes unsolved or is solved in a way that causes ongoing friction. I’ve helped a few API projects to solve this problem with the new OpenAPI Overlay specification so I thought I’d share! Continue reading →
28 Nov
2023

Add OpenAI flags to OpenAPI descriptions

With OpenAI’s new Actions feature allowing you to get a GPT that uses your own API, many new doors are open. However giving an AI an access token the keys to your API and telling it to have fun may lead you to realise that one of the doors available leads to the empty lift shaft of overwritten data, or the bottomless well of cloud bill shock. To reduce the risks, OpenAI supports an extension x-openai-isConsequential that you can add to your OpenAPI description, to indicate which endpoints should not be called without a human confirmation step.

I’m not doing much with OpenAI right now, but I do plenty with OpenAPI and the question “how do I add this field to my existing API description?” is one that I can answer! What’s more, you can use the advice in this post to add other extensions or additions to your OpenAPI descriptions using Overlays, this advice isn’t OpenAI-specific, but it’s used in the examples. Continue reading →

28 Feb
2023

Improve Existing OpenAPI Descriptions

I’m a firm fan of a design-first approach to building APIs, and advocate for it at every opportunity. Repeatedly. Design-first means that an API change starts in the OpenAPI description, gets reviewed and approved by the stakeholders, and then gets built afterwards.

I also live in the real world, where OpenAPI descriptions get generated from existing codebases, and engineering teams lack either the knowledge or the enthusiasm to modernise their processes. With a generated OpenAPI description, everything else that OpenAPI enables is likely to be disappointing, because the description only contains the information that was in the serverside code, and if you’re lucky some comment metadata. Enter OpenAPI Overlays, a way to describe alterations to an existing OpenAPI description that can be reapplied every time that description changes. Continue reading →