swagger: '2.0'

info:
  version: "0.0.1"
  title: changeserver
  description:
    Changeserver consumes changes from a Postgres replication scheme created
    by the "transicator_output" plugin and makes them available to consumers
    via an API. The API supports long polling so that a large number of
    consumers may be notified of changes.
  contact:
    name: Apigee, Inc.
    url: http://www.apigee.com/
    email: sales@apigee.com
  license: 
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

paths:
  /changes:
    get:
      description:
        Retrieve a list of changes. The query parameters may be used to
        restrict the number of changes that are retrieved or return
        only changes since a particular sequence. In addition, it
        is possible to block (aka "long poll") until a new matching
        change is available. The result will be produced in JSON format
        unless the Accept header is used to select the protobuf format.
      produces:
        - application/json
        - application/transicator+protobuf
      parameters:
        - name: scope
          in: query
          description:
            The scope limits the changes that are returned. It is
            extracted from a database column whenever a change is
            made. Every call to this API must contain at least one
            scope. Multiple "scope" parameters may also be used.
            if more than one "scope" is included, then the operation
            is treated as an "OR" of all the scopes, and the results
            are sorted by sequence regardless of scope.
          required: true
          type: string
        - name: selector
          in: query
          description:
            Alias for "scope" query parameter with the same usage.
            Completely interchangeable with "scope", which is no longer
            required if "selector" param is present.
          required: false
          type: string
        - name: snapshot
          in: query
          description:
            If specified, then this must be set to a "snapshot ID" from Postgres.
            This will be in the format "xmin:xmax:xip1,xip2,...xipN" and is
            normally returned by executing "select txid_current_snapshot()".
            By including this parameter, the change list will never include
            any data that would be *visible* in the specified snapshot.
            So in other words, if the value of this parameter comes from
            a Postgres query executed during a transaction, then the
            change server will not return any database changes that
            were already in the snapshot.
          required: false
          type: string
        - name: since
          in: query
          description:
            The value of "sequence" from a previous invocation of
            this API. If so specified, this API will only return changes
            that happened after the change with the specified sequence.
            Otherwise, this API will return changes since the
            beginning. If this parameter is specified, but the specified
            sequence no longer exists in the database, then a 400
            error and the error code "SNAPSHOT_TOO_OLD" will be
            returned.
          required: false
          type: string
        - name: limit
          in: query
          description:
            Limit the number of changes returned by a single API
            call. The default limit is 100.
          required: false
          type: integer
        - name: block
          in: query
          description:
            If specified, this sets the number of seconds that the API
            call will block if there are no changes available since the
            "since" value for the set of specified scopes. In the
            event that there are no changes available when the API call
            is made, the API will block for the specified number of
            seconds until a matching change appears. If no changes
            appear in the specified number of seconds, then an
            empty change list will be returned.
          required: false
          type: integer

      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/ChangeList'
        400:
          description: Invalid input. Error "code" will tell why.
            a code of "SNAPSHOT_TOO_OLD" means that records dating
            back to the "since" parameter are not available.
          schema:
            $ref: '#/definitions/Error'
            
  /health:
    get:
      description:
        Describes whether the server is "healthy." When the
        server is not healthy, it is not able to process any requests, and
        should be killed and restarted.
        If the server was started with a
        management port enabled, this URL only resolves on that
        port.
      produces:
        - text/plain
        - application/json
      responses:
        200:
          description: Everything is fine. No output produced.
        503:
          description: 
            Server is not healthy. Normally returns the status in textual
            form, but if JSON is selected in the Accept header than
            JSON will be returned.
          schema:
            $ref: '#/definitions/Status'
            
  /ready:
    get:
      description:
        Describes whether the server is "ready." When the
        server is not ready, it is not able to process any requests.
        Load balancers should not route calls to a server that is
        not ready. The server may not be ready because it is still
        starting up, or because it is shutting down. It is possible
        for a server to be "ready" but still "healthy."
        If the server was started with a
        management port enabled, this URL only resolves on that
        port.
      produces:
        - text/plain
        - application/json
      responses:
        200:
          description: Everything is fine. No output produced.
        503:
          description: 
            Server is not ready. Normally returns the status in textual
            form, but if JSON is selected in the Accept header than
            JSON will be returned.
          schema:
            $ref: '#/definitions/Status'
            
  /markdown:
    get:
      description:
        Changes the state of the server to denote that it has been
        marked down. After this is called, the "/ready" path will return
        503, and all other API calls except "/health" will also fail with
        503.
        After this API call has been made, the server will delete its
        Postgres replication slot when it exits. Management software
        should call this URL before a planned shutdown to ensure
        cleanup of Postgres resources.
        If the server was started with a
        management port enabled, this URL only resolves on that
        port.
      responses:
        200:
          description: Server is now marked down

definitions:
  Value:
    description:
      The value of a row in the "newRow" or "oldRow" property
      of a change.
    required:
      - value
      - type
    properties:
      value:
        description: The row value in string form
        type: string
      type:
        description: The Postgres numeric type of the field
        type: integer

  Change:
    description: A single change.
    properties:
      operation:
        description:
          The type of change.
          "1" denotes an insert.
          "2" denotes an update.
          "3" denotes a delete.
        type: integer
        enum:
        - 1
        - 2
        - 3
      table:
        description: The name of the database table that was changed.
        type: string
      sequence:
        description:
          The unique, ordered identifier of the change in the list of
          changes.
        type: string
      commitSequence:
        description:
          The order of this transaction's commit in the list of changes.
        type: integer
        format: int64
      changeSequence:
        description:
          The order of this change in the list of changes. Since
          transactions commit in different orders, changes are not
          necessarily shown in this order
        type: integer
        format: int64
      commitIndex:
        description:
          The order of this change in the list of changes for a
          particular transaction. When multiple changes are made in
          a transaction, they have the same commitSequence but
          different values of commitIndex.
        type: integer
        format: int64
      txid:
        description:
          The database transaction ID for this change
        type: integer
        format: int64
      newRow:
        description:
          The new value of the row for an insert or update operation.
          The fields in the object are named after the fields in the
          row, and each field's value is a "Value" object.
        type: object
      oldRow:
        description:
          The old value of the row for a delete or update operation.
        type: object

  ChangeList:
    description: A set of changes.
    properties:
      firstSequence:
        description: The oldest sequence present in the databse
        type: string
      lastSequence:
        description: The newest sequence present in the databse
        type: string
      changes:
        description: A list of changes, in sequence order.
        type: array
        items:
          $ref: '#/definitions/Change'
          
  Status:
    description: A response sent by a server that has been marked down.
    required:
      - status
      - reason
    properties:
      reason:
        description: 
          The reason that a server has been marked down. Suitable for
          writing in to logs and diagnostic errors.
        type: string
      status:
        description:
          If the server has been marked down, a reason why.
          One of "Unhealtly" or "NotReady".
          
  Error:
    description: An error in processing by the server.
    required:
      - code
      - error
    properties:
      code:
        description: A short symbolic description of the error
        type: string
      error:
        description: A short description of the error
        type: string
      description:
        description: A longer description of the error
        type: string