English

العربية

English

العربية

Appearance

Locale overlays ​

Locale overlays follow the OpenAPI Initiative Overlay Specification 1.x. They are stored per spec version, not copied when you upload a new version. This page is lookup detail. For why they exist, see Translated specifications. For publishing steps, see Exposing your API.

CLI flags and examples live in the apidex-cli README. This page does not replace that README.

Overlay document ​

Each overlay file is YAML or JSON with:

  • overlay — version 1.x.y
  • info.title — required
  • actions — non-empty list
  • each action — a JSONPath target plus update and/or remove

Example:

yaml
overlay: 1.1.0
info:
  title: Dutch overlay
  version: 1.0.0
actions:
  - target: $.info
    update:
      description: Nederlandse overlay.
  - target: $.paths['/internal']
    remove: true

An unmatched JSONPath target fails in the portal upload UI and in apidex-cli validate. At read time the same unmatched target is a no-op (that action does nothing; other actions still apply).

The portal no longer reads vendor extensions such as x-description-nl-NL on the canonical spec. Put locale views in overlay files.

Supported locales ​

en-GB, nl-NL, de-DE, fr-FR, es-ES, se-SE, ar-SA.

A bare primary subtag (nl) or different casing (NL-nl) resolves to the canonical tag. An unsupported locale is rejected on write.

Read (GET) ​

Request the spec with ?locale= set to the portal language (for example nl-NL). The response header X-Apidex-Overlay is one of:

ValueMeaning
noneNo overlay was applied (canonical spec, or no locale requested)
appliedAn overlay for that locale was merged
fallbackAn overlay exists but apply failed; the body is the canonical spec

Downloads and exports follow the on-screen language, including remove and non-copy update. To fetch the canonical document, omit locale.

Write (PUT / DELETE) ​

PUT /api/specs/{id}/overlays upserts the locales in the payload. Locales already stored for that spec and not named in the PUT stay unchanged. Duplicate canonical locales in one payload are rejected.

DELETE /api/specs/{id}/overlays removes every overlay for that spec.

New spec versions ​

Overlays belong to a spec id. A new version starts without them unless you send overlay files again.

Upload (portal or upload-spec) refuses a new version that would drop published translations: no overlay files, or a subset of locales already on the portal. Equal or superset is allowed. --force does not bypass this. First-time specs with no overlays succeed.

apidex-cli validate --require-locales is opt-in. It is a CI completeness check, not the same as the portal drop check.

Categories and inherited specs ​

Overlays attach to a spec, not to a product display name.

  • Category overlays belong on the category spec.
  • A product with inheritSpec: true uses the category spec (and those overlays). Overlays declared on an inheriting product are ignored.
  • The category drop-check looks up the category spec, not an API product that happens to share the category name.
  • If overlay PUT fails after creating a category spec, that new spec is deleted (same as the portal UI). Deleting it can cascade inheritSpec product specs for the same category; re-run upload-spec to restore inherit links.