Portal API reference

The portal API reference is one interactive reference for your own APIs, published on your API Portal at /full-api-reference. You manage it under Content, API Reference. How it is built depends on your portal: you upload a single OpenAPI file, or, once your portal is catalog-led, Apiable composes it from your products.

How is the portal API reference built?

In one of two ways, and your portal decides which, not this page. Until your portal is catalog-led, you upload one OpenAPI file. Once it is catalog-led, Apiable composes the reference from the APIs in your products' Active plans.

A portal becomes catalog-led when an admin chooses Switch to catalog-led on the API Catalog screen, under Let the API Catalog master documentation. The switch also changes how plan documentation works, and it cannot be undone from the dashboard. See API Catalog before you switch.

How do you publish an uploaded API reference?

Open Content, API Reference, pick your OpenAPI file, check the preview, then choose Upload. Turn on Published to put the reference on your portal. This applies until your portal is catalog-led.

1. Open Content, API Reference.
2. Under Full API documentation, click the file control and choose your OpenAPI file, in JSON or YAML and smaller than 10 MB.
3. Apiable checks the file as soon as you pick it. A valid file shows its name in the control and renders in the preview below. An invalid one shows the reason in red under the control.
4. Choose Upload to make this file your reference. The button is active only after you pick a new file.
5. Turn on Published. Turn on Public too if the portal should show the reference page to visitors who are not signed in.

Picking a file and choosing Upload needs a role that can manage the portal: the Organisation Owner, an Organisation Admin or a Portal Admin. The Public and Published toggles need a role that can manage content, which the same three hold.

What is on the page for an uploaded reference?

Two toggles, the Full API documentation panel with the file control, the Cascade Changes panel, an Instructions panel, and a preview of the current file. Until you upload a file, the preview reads No API Reference uploaded.

How do you add your own endpoint descriptions?

In the preview, choose Edit on an endpoint's description, write your text, then choose Save. Your text replaces the spec's description for that endpoint, on the dashboard and on your portal. It saves straight away.

• Only endpoints that have an operation ID in the spec show Edit.
• You can use Markdown.
• Clear the text and save to go back to the spec's own description.
• Descriptions are stored with the reference settings, not in the file, and match endpoints by operation ID, method and path. They carry over when you upload a new version of the file with the same endpoints.

Custom descriptions are edited only while your portal uses an uploaded file. Descriptions saved before a portal became catalog-led keep showing on the portal, and the catalog-led page has no control to change them. Contact Apiable if you need them changed.

What does Cascade do?

With Cascades on, your custom endpoint descriptions also replace the descriptions of the same endpoints in your products' plan documentation on the portal. Endpoints match by operation ID, method and path. The toggle saves as soon as you switch it.

Cascade Changes is shown only while your portal uses an uploaded file. If it was on when your portal became catalog-led, it stays on, and the catalog-led page has no control to turn it off. Contact Apiable if you need it changed.

How does a catalog-led portal build the reference?

Apiable composes it from the APIs in the Active plans of your Active products, using each API's specification from the API Catalog. Every Active product contributes by default, or you pick the products. There is no file to upload.

Turning Include all products off starts you with an empty selection, so add the products you want. The Public and Published toggles work as they do for an uploaded file. Changing the product selection needs a role that can manage content.

Which APIs does each visitor see on a catalog-led portal?

Only the APIs of products they can access. Apiable decides this for each visitor before it composes their reference, from the product's Audience and Visibility and the visitor's team. Your dashboard preview shows every API in the selected products.

In the dashboard preview, APIs that not every visitor can see carry a badge: Login required, Restricted or Internal. When the selection includes internal or partner-only APIs, a note in the panel counts them and reminds you that consumers are served only the APIs they are entitled to. For how audience and visibility work, see Products.

What does the overlap panel tell you?

That two or more APIs define the same endpoint. The reference can show each endpoint only once, so one definition is kept. The panel Some APIs define the same endpoints appears with a count, and it stays hidden when nothing overlaps.

Open the panel to see each overlapping endpoint. For each one it shows the API whose definition is Shown:, the API that is Not shown:, and the product and plan each came from. To resolve an overlap, change one of the API specifications, or the plans that include those APIs.

How is the upload checked, and where does Spectral validation apply?

An uploaded file is checked only for being a valid OpenAPI document with an info section and at least one path. Spectral rules you set under Settings, API Validation apply to specs in your API Catalog, not to this upload.

On a catalog-led portal, the reference is built from API Catalog specs, so those specs are the ones your Spectral rules check. For the ruleset setting, see API spec viewer and validation.

Where does the reference appear on your portal?

At /full-api-reference on your API Portal, with a full-screen version at /full-api-reference/fullscreen. While Published is off, the address shows a not-found page. While Public is off, visitors who are not signed in see a prompt to sign in instead of the page.

How is this different from the Apiable Platform API reference?

The portal API reference shows your own APIs to your developers. The Apiable Platform API reference documents Apiable's own API for managing your account. They serve different audiences and live in different places.

Troubleshooting

Where to next