API Evangelist enhancement overlay for the aP Connect Agent REST API

overlay: 1.0.0
info:
  title: API Evangelist enhancement overlay for the aP Connect Agent REST API
  version: 1.0.0
extends: openapi/apriori-ap-connect-agent.yml
x-generated: '2026-08-06'
x-method: generated
x-source: openapi/apriori-ap-connect-agent.yml
x-rationale: >-
  aPriori's published aP Connect Agent REST API Reference Guide documents status codes but never an error
  body, never the async polling contract, and never the fact that the results payloads are open objects that
  carry the customer's User Defined Attributes. This overlay layers those semantics on as vendor extensions
  and richer descriptions WITHOUT mutating openapi/apriori-ap-connect-agent.yml. Every statement below is
  traceable to an aPriori page cited in errors/, conventions/, lifecycle/ or changelog/. Apply with any
  Overlay 1.0.0 processor.
actions:
- target: $.info
  description: Record the async polling contract and the absence of an error envelope at the document level.
  update:
    x-async-contract:
      pattern: fire-and-poll
      invoke: POST /api/workflows/{workflowIdentity}/{action}
      handle: WorkflowActionResult.jobId
      poll: GET /api/workflows/{workflowIdentity}/jobs/{jobIdentity}
      terminal_signal: WorkflowJob.completedAt populated and WorkflowJob.status terminal
      fetch_results_after_terminal_only: true
      non_terminal_response: 409
      cancel: POST /api/workflows/{workflowIdentity}/jobs/{jobIdentity}/cancel
      callbacks: none published
      see: conventions/apriori-conventions.yml
    x-error-envelope:
      published: false
      rfc9457: false
      note: Every non-2xx is documented with schema "No Content"; branch on the status code alone.
      see: errors/apriori-problem-types.yml
    x-idempotency:
      supported: false
      note: >-
        No idempotency key. Retrying run or runPartList after a timeout can start a second costing job;
        dedupe client-side on the returned jobId. The shutdown nonce is a single-use confirmation handshake,
        not general idempotency.
    x-rate-limits:
      published: false
    x-pagination:
      published: false
      note: >-
        Collection endpoints have no page/cursor/limit/offset. ServiceConfiguration.maxPartsToReturn is an
        Agent-side configuration value, not a request parameter.
- target: $.paths['/api/workflows/{workflowIdentity}/jobs/{jobIdentity}/results'].get.responses['409']
  description: Mark the 409 as the documented polling signal rather than a client error.
  update:
    x-retryable: true
    x-retry-strategy: >-
      Poll GET /api/workflows/{workflowIdentity}/jobs/{jobIdentity} until the job is terminal, then
      re-request results. aPriori publishes no Retry-After header and no backoff guidance.
- target: $.paths['/api/workflows/{workflowIdentity}/jobs/{jobIdentity}/parts/{plmPartIdentity}/results'].get.responses['409']
  description: Mark the per-part 409 as the documented polling signal.
  update:
    x-retryable: true
    x-retry-strategy: >-
      Same as the job-level results endpoint — wait for the job to reach a terminal state before retrying.
- target: $.components.schemas.PartCostingResult
  description: Record that this object is open — it carries the customer's User Defined Attributes.
  update:
    additionalProperties: true
    x-open-object:
      reason: User Defined Attributes (UDAs)
      since: aP Connect Agent 4.0.0 (2024-07-22)
      detail: >-
        The results response body includes every UDA defined in the customer's workflow setup, so the
        documented fields are a floor and not a ceiling.
      source: https://docs.apriori.com/en/Connect/apc/rn/release-notes/
- target: $.components.schemas.WorkflowJob
  description: Name the fields that make up the terminal-state test.
  update:
    x-terminal-state-fields: [status, completedAt]
    x-progress-fields: [componentsTotal, componentsProcessed, componentsFailed]
    x-in-band-error-field: errorMessage
- target: $.components.securitySchemes.SharedSecret
  description: Flag the operational risk of a credential in the query string.
  update:
    x-risk: >-
      A shared secret in the query string is written to proxy, load-balancer and web-server access logs.
      Prefer the JWT Bearer Authorization header, and enable Connector mTLS (Agent 5.2.0+) where available.
- target: $.components.securitySchemes
  description: >-
    Record the transport-level mTLS option aPriori added in June 2026. It is configured on the Connector at
    install time rather than expressed as an OpenAPI security scheme, so it is captured as an extension
    rather than as a mutualTLS scheme the caller can select per request.
  update:
    x-mutual-tls:
      supported: true
      since: '2026-06-30'
      requires: aP Connect Agent 5.2.0 or later
      configuration: Enable on the Connector; supply the aPriori-signed certificate during Agent install.
      unsupported_in: unattended (-q) install mode
      replaces: IP allowlisting of the Agent host
      source: https://docs.apriori.com/en/Connect/apc/rn/release-notes/