guestgraph-io Operations API

openapi: 3.2.0
info:
  title: GuestGraph Apaleo connector Operations API
  version: 0.2.0
  description: 'What an operator and Apaleo can call on the connector. Apaleo delivers events to the webhook endpoint; an operator reads the status, starts a full sync or a reconciliation, and follows a run. Everything else the connector does, it does on its own schedule.


    Removing and restoring one connection''s webhook subscription. The connector creates a subscription for every configured connection when it starts and confirms it during every reconciliation; these two paths are how an operator takes one away before a teardown and puts it back without a restart.'
  license:
    name: Apache-2.0
servers:
- url: /
security:
- OpsToken: []
tags:
- name: Operations
  description: What an operator calls
paths:
  /status:
    get:
      tags:
      - Operations
      operationId: getStatus
      summary: Is this connector fine, connection by connection
      responses:
        '200':
          description: The status document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '401':
          description: Missing or wrong token
  /connections/{connectionId}/sync/full:
    post:
      tags:
      - Operations
      operationId: startFullSync
      summary: Start a full sync of one connection's properties and bookings
      parameters:
      - $ref: '#/components/parameters/ConnectionId'
      responses:
        '202':
          description: Started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunStarted'
        '404':
          description: No such connection
        '409':
          description: A full sync is already running on this connection
        '401':
          description: Missing or wrong token
  /connections/{connectionId}/sync/reconcile:
    post:
      tags:
      - Operations
      operationId: startReconciliation
      summary: Start a reconciliation from one connection's sync points
      parameters:
      - $ref: '#/components/parameters/ConnectionId'
      responses:
        '202':
          description: Started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunStarted'
        '404':
          description: No such connection
        '409':
          description: A run is already in progress on this connection
        '401':
          description: Missing or wrong token
  /connections/{connectionId}/refresh:
    post:
      tags:
      - Operations
      operationId: startRefresh
      summary: Re-read one connection's held guest ids and apply the integrator rule
      parameters:
      - $ref: '#/components/parameters/ConnectionId'
      responses:
        '202':
          description: Started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunStarted'
        '404':
          description: No such connection
        '401':
          description: Missing or wrong token
  /connections/{connectionId}/runs/{runId}:
    get:
      tags:
      - Operations
      operationId: getRun
      summary: One run's progress and outcome
      parameters:
      - $ref: '#/components/parameters/ConnectionId'
      - name: runId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'
        '404':
          description: No such connection or run
        '401':
          description: Missing or wrong token
  /connections/{connectionId}/subscription:
    delete:
      tags:
      - Operations
      operationId: removeSubscription
      summary: Remove this connection's webhook subscription in Apaleo
      description: 'Deletes the subscription whose endpoint is this connection''s, and nothing else in the Apaleo account, so two connections sharing an account are independent. A statement of the end state rather than of an act: asking twice, or asking when none exists, succeeds and says so in `removed`. The absence lasts until the connector is restarted or the subscription is restored; a restart subscribes every configured connection again.'
      parameters:
      - $ref: '#/components/parameters/ConnectionId'
      responses:
        '200':
          description: No subscription now names this connection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionRemoved'
        '401':
          description: Missing or wrong token
        '404':
          description: No such connection
        '502':
          description: Apaleo refused or could not be reached; nothing was removed
    put:
      tags:
      - Operations
      operationId: restoreSubscription
      summary: Create this connection's webhook subscription again
      description: 'The same act the connector performs for every connection when it starts: creates the subscription, or replaces one whose endpoint, events or properties differ. Idempotent, and the way back from a removal without editing configuration or restarting.'
      parameters:
      - $ref: '#/components/parameters/ConnectionId'
      responses:
        '200':
          description: A subscription names this connection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionState'
        '401':
          description: Missing or wrong token
        '404':
          description: No such connection
        '502':
          description: Apaleo refused or could not be reached; nothing was created
components:
  schemas:
    ConnectionStatus:
      type: object
      required:
      - id
      - tenantLabel
      - account
      - properties
      - subscription
      - syncPoints
      - counters
      - pendingEvents
      - splitsAwaitingPerson
      - lastActivityAt
      - lastError
      properties:
        id:
          type: string
        tenantLabel:
          type: string
        account:
          type: string
        properties:
          type: array
          items:
            type: string
        subscription:
          type: object
          required:
          - active
          - eventTypes
          properties:
            active:
              type: boolean
            id:
              type:
              - string
              - 'null'
            eventTypes:
              type: array
              items:
                type: string
        syncPoints:
          type: array
          items:
            type: object
            required:
            - propertyId
            - modifiedThrough
            properties:
              propertyId:
                type: string
              modifiedThrough:
                type:
                - string
                - 'null'
                format: date-time
              lastFullSyncAt:
                type:
                - string
                - 'null'
                format: date-time
              lastReconcileAt:
                type:
                - string
                - 'null'
                format: date-time
        lastActivityAt:
          type:
          - string
          - 'null'
          format: date-time
          description: The last successful run or event; a gap longer than Apaleo's retry window starts a full sync.
        counters:
          description: Since the connection's state was created.
          type: object
          required:
          - versionsSubmitted
          - recordsSubmitted
          - duplicates
          - flaggedForReview
          - errors
          properties:
            versionsSubmitted:
              type: integer
            recordsSubmitted:
              type: integer
            duplicates:
              type: integer
            flaggedForReview:
              type: integer
            errors:
              type: integer
        pendingEvents:
          type: integer
          description: Deliveries stored and not yet successfully processed.
        splitsAwaitingPerson:
          type: integer
          description: Held guest ids whose refresh answered SPLIT or RETIRED.
        lastRefreshAt:
          type:
          - string
          - 'null'
          format: date-time
        lastError:
          type:
          - object
          - 'null'
          properties:
            at:
              type: string
              format: date-time
            where:
              type: string
              enum:
              - APALEO
              - ENGINE
              - DATABASE
            reason:
              type: string
              description: Never a payload
              never a credential.: null
    Status:
      type: object
      required:
      - connections
      properties:
        connections:
          type: array
          items:
            $ref: '#/components/schemas/ConnectionStatus'
    SubscriptionRemoved:
      allOf:
      - $ref: '#/components/schemas/SubscriptionState'
      - type: object
        required:
        - removed
        properties:
          removed:
            description: 'Whether this request deleted a subscription. False means there was none to delete, which is success: the end state asked for is the end state now.

              '
            type: boolean
          endpoint:
            description: 'The endpoint URL the removed subscription pointed at, so an operator taking away a stale one can see which address it was.

              '
            type:
            - string
            - 'null'
    RunStarted:
      type: object
      required:
      - runId
      properties:
        runId:
          type: string
          format: uuid
    Run:
      type: object
      required:
      - id
      - kind
      - startedAt
      - reservationsSeen
      - versionsSubmitted
      - recordsSubmitted
      - duplicates
      - flaggedForReview
      - errors
      properties:
        id:
          type: string
          format: uuid
        kind:
          type: string
          enum:
          - FULL
          - RECONCILE
          - REFRESH
        startedAt:
          type: string
          format: date-time
        finishedAt:
          type:
          - string
          - 'null'
          format: date-time
        outcome:
          type:
          - string
          - 'null'
          enum:
          - SUCCEEDED
          - FAILED
          - null
        reservationsSeen:
          type: integer
        versionsSubmitted:
          type: integer
        recordsSubmitted:
          type: integer
        duplicates:
          type: integer
        flaggedForReview:
          type: integer
        errors:
          type: integer
        lastError:
          type:
          - string
          - 'null'
    SubscriptionState:
      type: object
      required:
      - state
      - eventTypes
      properties:
        state:
          description: 'ACTIVE when Apaleo holds a subscription for this connection; REMOVED when an operator asked for none; MISSING when there is none and nobody asked, which is a fault; UNKNOWN before the first read.

            '
          type: string
          enum:
          - ACTIVE
          - MISSING
          - REMOVED
          - UNKNOWN
        id:
          description: Apaleo's id for the subscription, when there is one
          type:
          - string
          - 'null'
        eventTypes:
          type: array
          items:
            type: string
        checkedAt:
          description: When this was last read from or written to Apaleo
          type:
          - string
          - 'null'
          format: date-time
  parameters:
    ConnectionId:
      name: connectionId
      in: path
      required: true
      schema:
        type: string
      description: The connection's name from configuration.
  securitySchemes:
    OpsToken:
      type: http
      scheme: bearer