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.

OpenAPI Overlay Specification

The OpenAPI Overlay Specification has been around for a while but it didn’t have implementations (or I just haven’t seen them, which is possible, please correct me if appropriate!). However it solves problems that I see in almost every organisation I talk to – the OpenAPI description is lacking words, examples, links or other additions that would make the documentation output better; the client SDK generators need some metadata to give more detailed hints on how to handle specific fields; not all endpoints in the description file should be fed into another tool (some are private, or restricted).

All these are familiar problems and I hope that the Overlay specification receives the attention and wide adoption that it merits. There are also some other similar solutions in this space, such as the Redocly decorators feature, but having an open standard really appeals to me since it enables switching between tools easily.

A library for Overlays

I’ve recently had a bit of time for a side project, and decided to start building a NodeJS implementation of this thing that I keep claiming will solve so many of the API problems I see!

Please try out the code, you can find lornajane/openapi-overlays-js on GitHub. It’s early days and I suspect I have a lot more tests to write, but if you’re interested in taking it for a spin, please go ahead! I would love to hear what works (and what doesn’t).