overlay: 1.0.0
info:
  title: API Evangelist enhancements for NGINX Plus REST API
  version: 1.0.0
extends: ../openapi/f5-nginx-plus-api-openapi.yml
x-provenance:
  generated: '2026-09-07'
  method: generated
  source: Generated from the harvested contract openapi/f5-nginx-plus-api-openapi.yml plus the repo artifacts
    it feeds. The underlying spec was fetched verbatim from https://demo.nginx.com/swagger-ui/nginx_api.yaml
    on 2026-09-07 and is NOT modified by this overlay.
  target_title: NGINX Plus REST API
  target_version: '9.0'
actions:
- target: $.info
  description: Record where this contract was harvested from and which repo artifacts describe its runtime
    semantics.
  update:
    x-apievangelist:
      provider: F5
      providerId: f5
      harvested: '2026-09-07'
      harvested_from: https://demo.nginx.com/swagger-ui/nginx_api.yaml
      repository: https://github.com/nginx/nginx.org/blob/main/yaml/nginx_api.yaml
      artifacts:
        conventions: ../conventions/f5-conventions.yml
        errors: ../errors/f5-problem-types.yml
        authentication: ../authentication/f5-authentication.yml
        lifecycle: ../lifecycle/f5-lifecycle.yml
        conformance: ../conformance/f5-conformance.yml
        data_model: ../data-model/f5-data-model.yml
        rate_limits: ../rate-limits/f5-rate-limits.yml
        packages: ../packages/f5-packages.yml
- target: $.info
  description: State the real base URL model. These are customer-hosted control planes; the declared server
    is a placeholder, not a reachable host.
  update:
    x-base-url-model:
      model: customer-hosted
      effective_base: https://{nginx-host}/api/9
      note: The caller supplies the host. No F5-operated endpoint serves this API.
- target: $.info
  description: Summarise the authentication the provider documents, which this contract does not fully
    declare.
  update:
    x-authentication-note: No securityScheme is declared. Access control is enforced in the nginx.conf
      location that serves the API; write methods additionally require `api write=on;` or every mutation
      returns 405 MethodDisabled.
- target: $.info
  description: Point at the derived error catalog and note what the contract omits.
  update:
    x-error-note: errors/f5-problem-types.yml lists 36 enumerated internal error codes read out of this
      contract.
- target: $.info
  description: Integration notes an agent needs that are not expressible in the contract itself.
  update:
    x-integration-notes:
    - 'Version negotiation: GET / returns the array of API versions the running build supports; an unsupported
      /api/{n} returns 404 UnknownVersion.'
    - Upstream peer IDs are assigned by NGINX and are NOT stable across a configuration reload.
    - Collections are maps keyed by configuration name, not arrays. There is no pagination.
- target: $.info
  description: Record the measured absence of rate-limit signalling so a consumer does not go looking
    for headers that are never sent.
  update:
    x-rate-limit-signalling:
      headers: []
      status_on_exhaustion: null
      note: No rate-limit header or 429 response is declared in this contract, and F5 publishes no limits
        for its own APIs. See ../rate-limits/f5-rate-limits.yml.