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!

My starting point is always to prefer a “full fat” OpenAPI description, a single moment where all the API surface is available in one place, even if it means building out some API description pipeline or combining files to get there. The big advantage is being able to lint, transform and review changes within the wider context.

From this point, start to filter out the parts that shouldn’t be exposed externally. For example, perhaps you have a legacy endpoint that the API gateway needs to honour for historical reasons, but nobody should really know that it is there apart from that! Using the deprecated field on those endpoints makes it easier to filter out.

For example, here’s a very short example API description with a single deprecated endpoint:

openapi: "3.1.0"
info:
  version: 1.0.0
  title: Imaginary town
paths:
  '/locations':
    get:
      summary: All locations
      operationId: locationList
      deprecated: true
      responses:
        '200':
          description: Returns all locations
            content:
              application/json:

To remove the operations with deprecated: true, I use an overlay like this:

overlay: 1.0.0
info:
  title: Remove deprecated operations
  version: 1.0.0
actions:
- target: '$..paths..[?(@.deprecated==true)]'
  remove: true

Run it with your chosen overlay tool (I’m using Bump CLI so bump overlay openapi.yaml overlay.yaml > output.yaml works) and you are all set! The OpenAPI description is safe to share.

It’s not just the deprecated endpoints that you might not want to share. I also commonly see x-experimental for features that aren’t ready for general adoption yet, or other teams use tags to indicate the intended audience such as only pro users, or only partners.

What I like about gathering an “everything” OpenAPI version and then removing it is that it makes easier API governance and maintenance because you’re seeing the whole picture. But that you can publish API descriptions to different audiences or different tooling with as much redacted as you like! Generate one set of API documentation to share with your internal teams or early adopters, then use an Overlay to remove the experimental endpoints before publishing to your public developer portal.

The key points here are: API redaction is better than having informal documentation or multiple API descriptions, and Overlays make this easy. Your OpenAPI is not a one-time document, you’ll use it as a pipeline, applying many Overlays or other transforms during the build process.

What’s your favourite thing to do with an Overlay? Show me an example if you have one!