API Evangelist enhancements for the Workspot Control REST API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Workspot Control REST API
  version: 1.0.0
extends: openapi/workspot-control-openapi.json
x-generated: '2026-09-04'
x-method: generated
x-source: >-
  Derived from https://api.workspot.com/v2/api-docs plus Workspot's own published
  documentation at docs.workspot.com. This overlay records API Evangelist observations
  about the harvested contract; it never mutates the original, which is preserved verbatim
  at openapi/workspot-control-openapi-original.json.
actions:
- target: $.info
  description: Record catalog provenance and the observed contract shape.
  update:
    x-apievangelist-slug: workspot
    x-apievangelist-harvested: '2026-09-04'
    x-apievangelist-source-url: https://api.workspot.com/v2/api-docs
    x-apievangelist-spec-version: swagger-2.0
    x-apievangelist-operations: 105
    x-apievangelist-paths: 85
    x-apievangelist-definitions: 120

- target: $.info
  description: >-
    Record the JSON syntax defect in the provider's own published document. The upstream
    /v2/api-docs response is NOT valid JSON — three "example" arrays contain unquoted bare
    tokens. A strict parser rejects the whole document, which means most standard toolchains
    cannot consume Workspot's contract as served.
  update:
    x-apievangelist-source-defect:
      kind: invalid-json
      detail: >-
        Two "example" arrays serialize bare unquoted tokens instead of JSON strings —
        [550e8400-e29b-41d4-a716-446655440003, 550e8400-e29b-41d4-a716-446655440007] in
        DeleteStaleDeviceRequest.deviceIds, and [rdgw1, rdgw2] in the gateway-name example.
      impact: json.loads(), and any strict Swagger parser, fails on the document as served.
      remediation_applied: >-
        openapi/workspot-control-openapi.json is the byte-for-byte same document with only
        those bare tokens quoted, so it parses. No path, operation, parameter, response or
        definition was added, removed or altered.
      unmodified_original: openapi/workspot-control-openapi-original.json

- target: $.info
  description: Record that the contract omits its own security model.
  update:
    x-apievangelist-contract-gaps:
      security_schemes_declared: 0
      note: >-
        The document declares no securityDefinitions and applies no security to any of its
        105 operations, yet every operation declares 401 and 403 responses. The real model —
        OAuth 2.0 password grant with Basic client credentials, or an Entra ID token — exists
        only in prose at docs.workspot.com. An agent reading only the machine-readable
        contract cannot discover how to authenticate.
      declared_5xx_responses: 0
      declared_404_responses: 0
      declared_429_responses: 0
      throttling_documented_but_undeclared: >-
        The API guide documents 20 GET/min and 15 write/min per-customer throttling returning
        HTTP 429, but no operation declares a 429 response.
      captured_in:
      - authentication/workspot-authentication.yml
      - errors/workspot-problem-types.yml
      - rate-limits/workspot-rate-limits.yml

- target: $.info
  description: Record the servers the document does not name.
  update:
    x-apievangelist-servers:
      declared_host: api.workspot.com
      declared_schemes: null
      note: >-
        The Swagger declares host api.workspot.com and basePath / but no schemes array.
        Workspot's documentation states the PREFERRED base URLs are regional —
        https://api.us.workspot.com and https://api.eu.workspot.com — with api.workspot.com
        retained as the older address. All three serve this same document. A tenant is
        reachable only in the region hosting its Control deployment.
      verified_hosts:
      - {host: 'https://api.workspot.com', api_docs_status: 200}
      - {host: 'https://api.us.workspot.com', api_docs_status: 200}
      - {host: 'https://api.eu.workspot.com', api_docs_status: 200}

- target: $.info
  description: Record the asynchronous execution model, which the contract does not express.
  update:
    x-apievangelist-async-model:
      pattern: submit-then-poll
      note: >-
        23 operations declare 202 Accepted and return a StatusURL that must be polled via
        GET /v1.0/operation/{operationId} until status is Succeeded or Failed. The Swagger
        expresses this only as a 202 response; the polling contract, the InProgress status
        value and the errorInfo envelope are documented in prose alone.
      poll_operation: statusCheckUsingGET
      captured_in: conventions/workspot-conventions.yml

- target: $.tags
  description: >-
    Record that the entire 105-operation surface carries a single tag, "APIs", which makes
    tag-based navigation and per-resource spec splitting impossible without re-derivation.
  update:
    x-apievangelist-tagging:
      declared_tags: 1
      declared_tag_names: [APIs]
      operations_per_tag: 105
      note: >-
        Every operation is tagged "APIs". The natural resource groupings — pools, desktops,
        users, groups, bundles, cloudAppPools, applications, clouds, templates, rdgateways,
        globalDesktops, licenses, staleDevices, policies, reports, operation — are visible
        only in the path structure. Recovered in data-model/workspot-data-model.yml.

- target: $.info
  description: Record the write-safety posture agents most need before acting.
  update:
    x-apievangelist-agent-safety:
      idempotency: none
      idempotency_note: 63 mutating operations, no idempotency key or replay-protection contract.
      reversibility: documented
      reversibility_note: >-
        cancelMoveDesktopUsingPOST and cancelUpgradeDesktopUsingPOST are real reversal paths,
        but no time window is published for either, and no DELETE has any undo or restore.
      dry_run: partial
      dry_run_note: Templates support draftTemplateUsingPOST and previewTemplateUsingPOST; nothing else can be simulated.
      captured_in: conventions/workspot-conventions.yml