API Evangelist enhancements for the Engine Omni Partner API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Engine Omni Partner API
  version: 1.0.0
x-generated: '2026-08-04'
x-method: generated
x-source: openapi/_original/hotel-engine-omni-partner-api-2.4.0-swagger-original.json
x-note: >-
  Captures API Evangelist's enhancements over Engine's published Swagger 2.0 document without
  mutating it. The dominant gap this overlay records: the contract declares no
  securityDefinitions and no security requirement, yet mutual TLS is mandatory on every call —
  a client generated from the spec alone will fail the handshake with no indication why. Also
  records the undeclared 429 and the gRPC-only streaming RPCs that the HTTP/JSON projection
  drops. Swagger 2.0 cannot express mutualTLS, so this is annotation, not a securityDefinitions
  patch; the durable fix is for Engine to publish OpenAPI 3.1 (which its own
  engine-public/protoc-gen-openapi already emits).
extends: openapi/hotel-engine-omni-partner-api-openapi.yml
actions:
  - target: $.info
    update:
      x-apievangelist-provider: hotel-engine
      x-apievangelist-artifacts:
        authentication: authentication/hotel-engine-authentication.yml
        conventions: conventions/hotel-engine-conventions.yml
        errors: errors/hotel-engine-problem-types.yml
        lifecycle: lifecycle/hotel-engine-lifecycle.yml
        rate_limits: rate-limits/hotel-engine-rate-limits.yml
        data_model: data-model/hotel-engine-data-model.yml
        grpc: grpc/_index.yml
        skills: skills/_index.yml
      x-authentication:
        type: mutualTLS
        note: >-
          Mandatory client-certificate authentication on every operation, documented at
          https://engine-public.github.io/engine-partner-api/integration-guide.html and
          verified by live TLS probe. Not expressible in Swagger 2.0 securityDefinitions,
          therefore absent from this document.
        credential_request: omni-partnerships@engine.com
      x-request-id-header: com-engine-request-id
      x-idempotency:
        supported: false
        note: >-
          No idempotency key. Replay safety depends on the single-use continuation_token
          handed from ConfirmOffer to Book; a timed-out Book must be reconciled with
          GetBookings, never retried.
      x-rate-limit:
        headers: [ratelimit-limit, ratelimit-remaining, ratelimit-reset]
        throttled_status: 429
        model: per-endpoint burst (minute) + sustained (hour)
        docs: https://engine-public.github.io/engine-partner-api/rate-limits.html
        note: 429 is documented but declared on no operation in this document.
      x-error-envelope:
        format: google.rpc.Status
        discriminate_on: details[] typed error message field presence
        rfc9457: false
      x-companion-surface:
        protocol: gRPC
        endpoint: partner-api.engine.com:443
        note: >-
          The protos are the source of truth; this document is generated from them by
          grpc-gateway protoc-gen-openapiv2. Two RPCs carry no google.api.http annotation and
          therefore do not appear here at all.
        grpc_only_rpcs:
          - engine.shop.lodging.service.v1.LodgingShoppingService.FindBestOffersStreaming
          - engine.book.lodging.service.v1.LodgingBookingService.GetBookingsStreaming
      x-spec-gaps:
        - No securityDefinitions despite mandatory mTLS.
        - No 401/403 responses declared on any operation.
        - No 429 response declared despite published per-endpoint rate limits.
        - ContentService_GetProperties declares a 400 with no schema — the only untyped error in the contract.
        - Swagger 2.0 rather than OpenAPI 3.x.
  - target: $.paths['/book/v1/lodging/booking'].put
    update:
      x-agentic-consequence: physical
      x-idempotent: false
      x-human-in-the-loop: recommended
      x-note: >-
        Spends real money and cannot be safely retried. On ambiguity call
        LodgingBookingService_GetBookings to reconcile.
      x-non-retriable-errors: [needsReview, paymentProcessing]
  - target: $.paths['/book/v1/lodging/booking/submit-cancellation'].post
    update:
      x-agentic-consequence: physical
      x-idempotent: false
      x-human-in-the-loop: recommended
      x-note: >-
        Irreversible and refund-bearing. Call LodgingBookingService_PreviewCancellation first
        to obtain the expected refund before submitting.
  - target: $.paths['/book/v1/lodging/confirm-offer'].post
    update:
      x-price-lock: true
      x-note: >-
        Returns a Quote whose price is locked for a limited window. The quote is perishable —
        re-confirm rather than booking against a stale one.
  - target: $.paths['/book/v1/lodging/booking'].post
    update:
      x-partial-failure: true
      x-note: >-
        GetBookingsError.errors[] carries one GetBookingError per booking that could not be
        retrieved; some ids can succeed while others fail in the same call. This is also the
        reconciliation endpoint after an ambiguous Book.
  - target: $.paths['/book/v1/lodging/booking/generate-folio'].post
    update:
      x-response-encoding: binary
      x-note: Returns google.api.HttpBody — an Engine-branded folio PDF, not a JSON envelope.
  - target: $.paths['/shop/v1/lodging/best-offers'].post
    update:
      x-note: >-
        Returns one best-priced offer per property plus a continuation_token; NOT the
        exhaustive rate set. Pass the token to FindAvailability for the full room/offer detail.
      x-grpc-streaming-variant: FindBestOffersStreaming
  - target: $.paths['/content/v1/property'].get
    update:
      x-pagination:
        style: page-token
        request: [page_size, page_token]
        response: [next_page_token]
      x-rate-limit: {burst_per_minute: 400, sustained_per_hour: 18000}
  - target: $.paths['/content/v1/properties'].post
    update:
      x-note: The 400 response declares no schema — clients receive only the rpcStatus message string.