API Evangelist enhancements for the MikMak Commerce API (v1)

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the MikMak Commerce API (v1)
  version: 1.0.0
extends: ../openapi/mikmak-commerce-api-openapi.yml
x-provenance:
  generated: '2026-08-12'
  method: generated
  source: >-
    Enhancements over the provider's own spec. The base document was assembled verbatim from the
    per-operation OpenAPI 3.0.0 blocks MikMak publishes on its ReadMe reference pages
    (https://docs.mikmak.ai/reference/get_commerce-v1-*.md); the eight slices merged with zero
    conflicting definitions. Ownership confirmed - servers[] is https://api.mikmak.ai, the
    ReadMe project name is "MikMak", and the Insights API is served live from the same host.
  base_spec_operations: 8
  note: >-
    The original is never mutated. This overlay records what MikMak's published contract is
    missing - operationIds on every operation, a documented error body, a 429 response, and the
    one-of location constraint the MCP layer enforces but the REST spec does not express.
actions:
  - target: $.info
    description: Record the contract's real base and contact posture.
    update:
      contact:
        name: MikMak
        url: https://docs.mikmak.ai/reference/mikmak-headless-commerce-api
      x-api-evangelist-note: >-
        Use of this API requires explicit contractual approval from MikMak's Commercial teams;
        deployment on third-party sites or unauthorized resellers is prohibited.
  - target: $.paths['/commerce/v1/products/{id}'].get
    description: Add the missing operationId.
    update:
      operationId: getProducts
  - target: $.paths['/commerce/v1/search/products'].get
    description: Add the missing operationId.
    update:
      operationId: searchProducts
  - target: $.paths['/commerce/v1/products/facet'].get
    description: Add the missing operationId.
    update:
      operationId: getProductFacets
  - target: $.paths['/commerce/v1/availabilities/{id}'].get
    description: Add the missing operationId.
    update:
      operationId: getAvailabilities
  - target: $.paths['/commerce/v1/availabilities/cart/{id}'].get
    description: Add the missing operationId.
    update:
      operationId: getCartAvailabilities
  - target: $.paths['/commerce/v1/productcatalog/offers/models/{id}'].get
    description: Add the missing operationId.
    update:
      operationId: getModelOffers
  - target: $.paths['/commerce/v1/experiences'].get
    description: Add the missing operationId.
    update:
      operationId: listExperiences
  - target: $.paths['/commerce/v1/experiences/config/{id}'].get
    description: Add the missing operationId.
    update:
      operationId: getExperienceConfig
  - target: $.components.securitySchemes.ApiKeyAuth
    description: Record that the key is issued out of band and is server-side only.
    update:
      x-issuance: manual
      x-note: >-
        Issued by a MikMak representative at onboarding. There is no self-service signup. The
        provider's documentation forbids using this key in frontend, mobile or client-side
        JavaScript.
  - target: $.components.securitySchemes.JWTBearerAuth
    description: Record the OAuth endpoints that back this bearer token.
    update:
      x-token-url: https://api.mikmak.ai/commerce/v1/oauth/token
      x-authorization-url: https://api.mikmak.ai/commerce/v1/authorize
      x-grants:
        - client_credentials
        - authorization_code
        - refresh_token
      x-note: >-
        MikMak's token endpoint accepts a JSON body rather than the form-encoded body RFC 6749
        specifies. See authentication/mikmak-authentication.yml.
  - target: $.paths['/commerce/v1/availabilities/{id}'].get
    description: Express the one-of location rule the MCP layer enforces but the spec omits.
    update:
      x-location-constraint:
        rule: exactly-one-of
        options:
          - [postal_code, country]
          - [latitude, longitude]
        enforcement: >-
          Rejected by the MCP server's input-schema validation with "Do not mix location
          methods." Not expressed in this OpenAPI.
  - target: $.paths['/commerce/v1/products/{id}'].get
    description: Express the same one-of location rule on product detail.
    update:
      x-location-constraint:
        rule: exactly-one-of
        options:
          - [postal_code, country]
          - [latitude, longitude]
  - target: $.components
    description: >-
      Contribute the error and rate-limit contract MikMak documents in prose but does not put in
      the spec. Every 4xx/5xx in the base document has a description and no content schema.
    update:
      schemas:
        ProblemDetails:
          type: object
          description: >-
            RFC 7807 problem document, as returned by the MikMak Commerce MCP Server and
            verified live on 2026-08-12. Contributed by API Evangelist; the Commerce REST
            surface declares no error body of its own.
          properties:
            type:
              type: string
            title:
              type: string
            status:
              type: integer
            detail:
              type: string
            instance:
              type: string
            code:
              type: string
              enum:
                - AUTH_UNAUTHORIZED
                - MIKMAK_UNAUTHORIZED
                - MIKMAK_FORBIDDEN
                - RATE_LIMITED
            source:
              type: string
      headers:
        X-Request-Id:
          description: Client-supplied trace id echoed into MikMak server logs; generated server-side when absent.
          schema:
            type: string
        X-RateLimit-Limit:
          description: The active cap for this caller.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Requests left in the current window. Returned on 2xx as well as 429.
          schema:
            type: integer
        Retry-After:
          description: Seconds to wait before retrying after a 429.
          schema:
            type: integer
      responses:
        TooManyRequests:
          description: >-
            Rate cap exceeded. Documented by MikMak with body code RATE_LIMITED, but not
            declared on any operation in the base spec.
          headers:
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  - target: $.tags
    description: Declare the tag set the operations already use but the document never defines.
    update:
      - name: Product
        description: Product metadata lookup by GTIN/UPC/EAN.
      - name: Product Search
        description: Free-text and filtered product search with server-controlled pagination.
      - name: Facet
        description: Product facets and productId selection.
      - name: Availabilities
        description: Location-scoped retailer availability, price, stock and delivery mode.
      - name: Cart
        description: Store-grouped multi-product cart availability with per-store totals.
      - name: Offers
        description: Online and local retailer offers for a manufacturer model.
      - name: Experiences
        description: Experience listing and configuration metadata.