overlay: 1.0.0
info:
  title: API Evangelist enrichment overlay — RELEX Data API
  version: 1.0.0
extends: ../openapi/relex-data-api-openapi.json
x-generated: '2026-08-26'
x-method: generated
x-source: >-
  Generated by the API Evangelist enrichment pipeline from artifacts in this repo
  (conventions/, errors/, rate-limits/, lifecycle/, asyncapi/, authentication/). It records OUR
  annotations; it never mutates the original contract, which stays byte-faithful in openapi/.
actions:
- target: $.info
  description: Record contract provenance — RELEX serves no standalone spec file; this document was
    lifted from the embedded ReDoc hydration state of RELEX's own published reference page.
  update:
    x-apievangelist-source: https://www.relexsolutions.com/api/retail-restapi-example-customer.html
    x-apievangelist-extraction: 'embedded __redoc_state (ReDoc 2.1.5) — no .json/.yaml is served'
    x-apievangelist-customer-specific: true
    x-apievangelist-customer-specific-note: >-
      RELEX publishes this as "RELEX Data API for Example Customer". The Custom tag and the data
      model half of info.version are per customer, so a given customer's contract will differ in
      its custom resources and its version number, while the meta/, master/ and transactions/
      surface and every convention below are shared.
- target: $.info
  description: Attach the runtime semantics an agent needs but the contract does not state.
  update:
    x-rate-limit:
      requests_per_second: 5
      max_request_bytes: 1048576
      negotiable: true
      status_on_exhaustion: 429
      status_on_oversize: 413
      headers: []
    x-idempotency:
      supported: true
      mechanism: verb-level; POST (upsert) and DELETE are both idempotent
      key_field: meta.batch_id
      key_format: uuid
      rule: retries of the same logical request MUST reuse the same batch_id
      header: null
    x-async-write-semantics:
      note: A 2xx on a write means ACCEPTED, not processed. Ingestion errors surface later.
      confirmation_operation: GetErrors
      confirmation_key: request_id
    x-reversibility:
      grade: documented
      window_stated: false
      transactional_writes_reversible: false
      master_data_deletable: true
    x-versioning:
      scheme: semver
      composition: core version + per-customer data model version, summed
      discovery_operation: GetVersion
      breaking_change_window: 3 months behind a feature flag defaulting to existing behaviour
      sunset_header: false
    x-webhooks:
      present: true
      provider: svix
      signature: HMAC-SHA256 via SVIX-SIGNATURE
      payload: metadata only — fetch the record with a follow-up GET
      catalog: asyncapi/relex-data-api-webhooks.yml
- target: $.servers
  description: Note that the published servers[] are the example-customer hosts, and record the
    documented host pattern.
  update:
    x-apievangelist-host-pattern: 'https://{env-geography}.rest.relexsolutions.com/{customer}'
    x-apievangelist-environments:
      uat: uat-eu.rest.relexsolutions.com
      production: eu.rest.relexsolutions.com
    x-apievangelist-regions:
    - eu
    - us
- target: $.components.securitySchemes.OAuth2
  description: Point the oauth2 scheme at the live OpenID Connect discovery documents captured in
    well-known/.
  update:
    x-openid-configuration-eu: https://identity.prod-eu.prod.cc.relexsolutions.com/login/restapi_prod/.well-known/openid-configuration
    x-openid-configuration-us: https://identity.prod-us.prod.cc.relexsolutions.com/login/restapi_prod/.well-known/openid-configuration
    x-refresh-tokens: false
    x-token-endpoint-auth-methods:
    - client_secret_basic
    - client_secret_post
    x-credential-issuance: issued by RELEX during the implementation project; no self-service
- target: $.paths['/meta/errors'].get
  description: Flag the operation as the mandatory confirmation step for every asynchronous write.
  update:
    x-apievangelist-role: write-confirmation
    x-apievangelist-note: >-
      Poll with the request_id returned by a POST or DELETE until processing settles. Results can
      grow between polls because ingestion is asynchronous. Paged via page/per_page (max 10000)
      with _links.next.
- target: $.tags
  description: Record that the Custom tag is per-customer.
  update:
    x-apievangelist-custom-tag-note: Resources under the Custom tag are provisioned per customer
      and will not exist in another customer's contract.