{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"hide-your-internal-apis","__idx":0},"children":["Hide your internal APIs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Several times a month, a variation of this question comes up:"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["How do we hide endpoints that are for internal use only?"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Follow along using our sample API provided with this tutorial to hide APIs, and then try this again with your APIs."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"graph TD\n A[SSOT] -->|bundle| B(Internal)\n A[SSOT] -->|bundle| C(External)\n","diagramHtml":"

bundle

bundle

SSOT

Internal

External

","diagramHtmlDark":"

bundle

bundle

SSOT

Internal

External

"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following image highlights what is to be removed in this tutorial."," ",{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/hide-internal-apis-problem-dc353629a8944264.png","alt":"what needs to be hidden"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":2},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"We do, You do"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This tutorial is most effective when you follow along and complete the steps."]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/installation"},"children":["Install @redocly/cli"]}," with version 1.0.0-beta.90 or later (we use 1.0.0-beta.94 in this tutorial)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Download the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://gist.github.com/adamaltman/ee07bf94a967926ee0e54bcd56fdcdfb"},"children":["sample.yaml"]}," file into a new directory named ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hide-apis-demo"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use your favorite IDE for editing the YAML file (we use VS Code and have the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/docs/redocly-openapi/"},"children":["Redocly extension"]}," installed)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-add-x-internal-to-the-api-description","__idx":3},"children":["Step 1: Add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-internal"]}," to the API description"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this step, mark which operations and properties of the API description are for internal use."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Open the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sample.yaml"]}," file in your IDE. Changes are needed in a few places."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Go to line 22 and add a new line between ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["post"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationId"]},"."," ","The indentation is important."," ","Type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-internal: true"]}," on that line."," ","The space after the colon is important too."," ","It should look like the following example.",{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"post:\n x-internal: true\n operationId: postStars\n","lang":"yaml"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Go to line 52 and add a new line between ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hasPlanets"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]},", like we did previously. The following example shows how it should look.",{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"hasPlanets:\n x-internal: true\n type: boolean\n","lang":"yaml"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Save the file."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-add-a-redocly-configuration-file","__idx":4},"children":["Step 2: Add a Redocly configuration file"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this step, create a Redocly configuration file with two APIs pointing to the same root file."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Make a new file in the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hide-apis-demo"]}," directory named ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," (the casing is important)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Then, add this snippet to the file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"apis:\n internal@latest:\n root: ./sample.yaml\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Let's explain what's going on here."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apis"]}," object contains a collection of our APIs."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internal@latest"]}," matches the expected configuration ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{name@version}"]}," pattern for each API."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["root"]}," is the path to the root of the API description."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We only have one root API file (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sample.yaml"]},"), but we want to generate two APIs from that SSOT."," ","To do that, we add another API to the API section."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"apis:\n internal@latest:\n root: ./sample.yaml\n external@latest:\n root: ./sample.yaml\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Finally, we want the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/decorators/remove-x-internal"},"children":["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."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"apis:\n internal@latest:\n root: ./sample.yaml\n external@latest:\n root: ./sample.yaml\n decorators:\n remove-x-internal: on\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," file."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-output-internal-and-external-apis","__idx":5},"children":["Step 3: Output internal and external APIs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this step, produce two API snapshots from the single source of truth."," ","This can be done in two ways:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Option A: Let Redocly's API registry handle the work (which uses the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bundle"]}," command under the hood)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Option B: Your machine plus the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v2/commands/bundle"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bundle"]}," command"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"option-a-redoclys-api-registry-bundles-automatically","__idx":6},"children":["Option A: Redocly's API registry bundles automatically"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add the APIs to the API registry."," ","This process varies depending on the source type you use."," ","If using the CICD ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["push"]}," command, it can push all APIs or the API you specify by the API ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name@version"]},"."," ","If using a git-based integration, select the appropriate API in the path to your root file."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/content-assets/hide-apis-path-to-root-file-6f2743ef7cdc0452.png","alt":"path to root file"},"children":[]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Confirm the API in the registry has the appropriate content."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Repeat this step for each API."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"option-b-use-your-machine-and-the-bundle-command","__idx":7},"children":["Option B: Use your machine and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bundle"]}," command"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Bundle the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external@latest"]}," API."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"redocly bundle external@latest --output dist/external.yaml\n","lang":"shell"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Inspect the file at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dist/external.yaml"]},"."," ","Confirm the following:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["postStars"]}," operation is removed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hasPlanets"]}," property is removed."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Bundle the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internal@latest"]}," API."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"redocly bundle internal@latest --output dist/internal.yaml\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Inspect the file at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dist/internal.yaml"]},"."," ","Confirm the following:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["postStars"]}," operation is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," removed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hasPlanets"]}," property is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," removed."]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":8},"children":["Next steps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you enjoyed this tutorial, please share it with a colleague, or on the social networks."," ","Be sure to tag ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@Redocly"]}," as it lets us know how we're doing and where we can improve."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Try this technique with your own APIs to accomplish the use case demonstrated above."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"Security through obscurity"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If an endpoint is discovered, your API authentication mechanism ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["must"]}," prevent unauthorized access."," ","Removing APIs from documentation is not a security mechanism. Use access controls for your internal API documentation as well."]}]}]},"frontmatter":{"tocMaxDepth":3},"tagList":["admonition"],"title":"Hide your internal APIs","lastModified":"2026-02-11T08:45:02.000Z"}