API Evangelist enhancements for the Watchmaker Genomics Storefront REST API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Watchmaker Genomics Storefront REST API
  version: 1.0.0
x-provenance:
  generated: '2026-09-04'
  method: generated
  source: openapi/watchmaker-genomics-commerce-rest-swagger.json
  note: >-
    Non-destructive enhancements over the Swagger 2.0 document Watchmaker Genomics' storefront
    self-serves at /rest/all/schema?services=all. The original is preserved verbatim and is never
    mutated. Every action below records something observed on the live host or read from a sibling
    artifact in this repo — a missing description, a real base URL, an undeclared 401, an
    irreversibility fact — and nothing invents API behaviour.
actions:
- target: $.info
  description: >-
    The published document carries only {version: "2.4", title: "Magento Enterprise"} — the
    platform's identity, not the operator's. Name the operator and give the contract a description
    and a contact, which contract_quality's info_complete check reads.
  update:
    title: Watchmaker Genomics Storefront REST API
    description: >-
      The Adobe Commerce (Magento 2.4) REST API as deployed by Watchmaker Genomics on its own host,
      www.watchmakergenomics.com. Self-described at /rest/all/schema?services=all. The anonymous
      slice — directory, guest carts, checkout estimation and order placement, customer account
      creation, gift cards, in-store pickup, search and the Magefan blog — answers without a
      credential; every other operation returns 401 naming the Magento ACL resource it needs.
      Watchmaker Genomics publishes no developer documentation for this surface; it exists because
      the platform serves it.
    x-operator: Watchmaker Genomics
    x-operator-url: https://www.watchmakergenomics.com/
    x-platform: Adobe Commerce (Magento 2.4)
    x-platform-note: >-
      info.title in the original reads "Magento Enterprise" because the document is generated by
      the platform. Ownership was verified from the deployment, not the title — the schema's own
      host field is www.watchmakergenomics.com, the WSDL targetNamespace is
      https://www.watchmakergenomics.com/soap/all, and a live GraphQL storeConfig query returns
      base_url https://www.watchmakergenomics.com/ over Watchmaker's own SKUs.
    contact:
      name: Watchmaker Genomics Support
      email: support@watchmakergenomics.com
      url: https://www.watchmakergenomics.com/technical-support
- target: $
  description: Record the callable base and the store-scope variants observed to resolve.
  update:
    x-base-url: https://www.watchmakergenomics.com/rest/all
    x-store-scopes:
    - {scope: all, path: /rest/all, note: All store views. Verified 200.}
    - {scope: default, path: /rest/default, note: Default store view. Verified 200, identical schema.}
    x-schema-source: https://www.watchmakergenomics.com/rest/all/schema?services=all
    x-verified-anonymous:
    - {operationId: GetV1DirectoryCurrency, url: 'https://www.watchmakergenomics.com/rest/V1/directory/currency', status: 200, fetched: '2026-09-04'}
- target: $.securityDefinitions.api_key
  description: >-
    The original declares the scheme but says nothing about how a caller obtains a key, and the
    document never applies security to any operation.
  update:
    description: >-
      Magento integration access token. Also accepted as `Authorization: Bearer <token>`. Tokens
      are issued by POST /V1/integration/admin/token or POST /V1/integration/customer/token, both
      of which are in this document — but note that the storefront's own account routes
      (/customer/account/create/, /customer/account/login/) return 404, so no member of the public
      can obtain one. The credentialed surface is effectively closed.
- target: $.paths
  description: >-
    401 is returned in practice and declared nowhere in the 70-operation surface. Record it at the
    document level so a consumer reading the contract is not surprised by it.
  update:
    x-undeclared-responses:
    - status: 401
      schema: '#/definitions/error-response'
      evidence:
        url: https://www.watchmakergenomics.com/rest/V1/store/storeConfigs
        status: 401
        body: '{"message":"The consumer isn''t authorized to access %resources.","parameters":{"resources":"Magento_Backend::store"}}'
      note: >-
        Returned by every operation outside the anonymous slice. parameters.resources names the
        required ACL resource. See errors/watchmaker-genomics-problem-types.yml.
- target: $.paths['/V1/guest-carts/{cartId}/order'].put
  description: >-
    The single most consequential operation on the surface, and the contract says nothing about
    whether it can be undone. Attach the irreversibility fact, read live from the store's own
    configuration.
  update:
    x-consequence: irreversible
    x-reversibility:
      grade: documented
      reversal_operation: 'GraphQL cancelOrder (this REST surface has no cancel operation at all)'
      available: false
      window: null
      evidence:
        url: https://www.watchmakergenomics.com/graphql
        query: '{storeConfig{order_cancellation_enabled returns_enabled}}'
        result: {order_cancellation_enabled: false, returns_enabled: disabled}
        fetched: '2026-09-04'
      note: >-
        Order cancellation and returns are both switched OFF on this store. An agent placing an
        order here cannot take it back programmatically. Recovery is human:
        orders@watchmakergenomics.com or +1-720-543-2174.
    x-escalation: human-approval-required
- target: $.paths['/V1/guest-carts/{cartId}/estimate-shipping-methods'].post
  description: Mark the genuine dry-run path so an agent can rehearse before committing.
  update:
    x-consequence: read-only
    x-dry-run: true
    x-note: >-
      Computes shipping options for an address without mutating the cart or creating an order.
      Pair with POST /V1/guest-carts/{cartId}/totals-information to price the whole basket before
      calling PUT /V1/guest-carts/{cartId}/order.
- target: $.paths['/V1/guest-carts/{cartId}/totals-information'].post
  update:
    x-consequence: read-only
    x-dry-run: true
- target: $.paths['/V1/customers'].post
  description: Record that the API-side account flow is open while the web-side one is not.
  update:
    x-note: >-
      Account creation answers on the API while the storefront routes /customer/account/create/
      and /customer/account/login/ both return 404 (probed 2026-09-04). Anyone integrating should
      confirm with Watchmaker that self-service registration is intended to be reachable here.
- target: $
  description: Record what this contract does NOT contain, which is the finding an integrator needs first.
  update:
    x-coverage-gaps:
    - >-
      NO product or category read operations exist in this REST surface. GetV1Productsrenderinfo is
      a price/render-block helper and GetV1Search is a generic quick search. The Watchmaker
      catalog — SKUs, descriptions, media, tier prices, stock, custom attributes — is reachable
      only through the GraphQL endpoint at https://www.watchmakergenomics.com/graphql.
    - No rate limits are declared and no 429 response appears on any operation.
    - No idempotency mechanism exists on any of the 70 operations.
    - Errors use the Magento envelope, not RFC 9457 application/problem+json.
    x-companion-surfaces:
    - {type: GraphQL, url: 'https://www.watchmakergenomics.com/graphql', artifact: graphql/watchmaker-genomics-commerce.graphql}
    - {type: WSDL, url: 'https://www.watchmakergenomics.com/soap/all?wsdl_list=1', artifact: wsdl/watchmaker-genomics-commerce-soap.wsdl}