Hide your internal APIs

Several times a month, a variation of this question comes up:

How do we hide endpoints that are for internal use only?

Follow along using our sample API provided with this tutorial to hide APIs, and then try this again with your APIs.

Overview

In this tutorial, see how to maintain a single source of truth (SSOT) OpenAPI description. Once the API description is complete, generate an internal and an external version of the API.

The following image highlights what is to be removed in this tutorial.

Prerequisites

• Install @redocly/cli with version 1.0.0-beta.90 or later (we use 1.0.0-beta.94 in this tutorial).
• Download the sample.yaml file into a new directory named hide-apis-demo.
• Use your favorite IDE for editing the YAML file (we use VS Code and have the Redocly extension installed).

Step 1: Add x-internal to the API description

In this step, mark which operations and properties of the API description are for internal use.

Open the sample.yaml file in your IDE. Changes are needed in a few places.

1. Go to line 22 and add a new line between post and operationId. The indentation is important. Type x-internal: true on that line. The space after the colon is important too. It should look like the following example.
   post:
     x-internal: true
     operationId: postStars
   

2. Go to line 52 and add a new line between hasPlanets and type, like we did previously. The following example shows how it should look.
   hasPlanets:
     x-internal: true
     type: boolean
   

3. Save the file.

Step 2: Add a Redocly configuration file

In this step, create a Redocly configuration file with two APIs pointing to the same root file.

Make a new file in the same hide-apis-demo directory named redocly.yaml (the casing is important).

Then, add this snippet to the file:

apis:
  internal@latest:
    root: ./sample.yaml

Let's explain what's going on here. The apis object contains a collection of our APIs. The internal@latest matches the expected configuration {name@version} pattern for each API. The root is the path to the root of the API description.

We only have one root API file (sample.yaml), but we want to generate two APIs from that SSOT. To do that, we add another API to the API section.

apis:
  internal@latest:
    root: ./sample.yaml
  external@latest:
    root: ./sample.yaml

Finally, we want the remove-x-internal decorator to be applied to the external API. To accomplish that, add the last three lines as shown in the following example.

apis:
  internal@latest:
    root: ./sample.yaml
  external@latest:
    root: ./sample.yaml
    decorators:
      remove-x-internal: on

Save the redocly.yaml file.

Step 3: Output internal and external APIs

In this step, produce two API snapshots from the single source of truth. This can be done in two ways:

• Option A: Let Redocly's API registry handle the work (which uses the bundle command under the hood).
• Option B: Your machine plus the bundle command.

Option A: Redocly's API registry bundles automatically

1. Add the APIs to the API registry. This process varies depending on the source type you use. If using the CICD push command, it can push all APIs or the API you specify by the API name@version. If using a git-based integration, select the appropriate API in the path to your root file.

   

2. Confirm the API in the registry has the appropriate content.

3. Repeat this step for each API.

Option B: Use your machine and the bundle command

1. Bundle the external@latest API.

   redocly bundle external@latest --output dist/external.yaml
   

2. Inspect the file at dist/external.yaml. Confirm the following:

   • The postStars operation is removed.
   • The hasPlanets property is removed.

3. Bundle the internal@latest API.

   redocly bundle internal@latest --output dist/internal.yaml
   

   Inspect the file at dist/internal.yaml. Confirm the following:

   • The postStars operation is not removed.
   • The hasPlanets property is not removed.

Next steps

If you enjoyed this tutorial, please share it with a colleague, or on the social networks. Be sure to tag @Redocly as it lets us know how we're doing and where we can improve.

Try this technique with your own APIs to accomplish the use case demonstrated above.