snapshot-api.yaml

swagger: "2.0"
info:
  version: "0.0.1"
  title: snapshotserver
  description:
    The Snapshot server produces a consistent view of data in a Postgres database
    for a set of "scopes." Each scope is a unique string identified by a column
    called "_apid_scope" in each table. Tables with no such column are
    ignored.
  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
  
consumes:
  - application/json
produces:
  - application/json
paths:
  /snapshots:
    get:
      summary: Get data for a particular snapshot
      description: 
        Generate and create the data for a snapshot. The snapshot will contain
        data from all tables in the current database and schema that has a
        column named "_apid_scope" that matches one of the "scope" values.
        The generated snapshot includes JSON data by default. The "Accept" header
        may be used to request data in protocol buffer format.
      produces:
        - application/json
        - application/transicator+protobuf
        
      parameters:
        - name: scope
          in: query
          required: true
          type: string
          description:
            The "scope" field represents a unique identifier that is required in
            order to generate a snapshot. The snapshot will contain data from all
            tables that have an "_apid_scope" column that matches the value.
            At least one scope must be included. If multiple scopes are included,
            then the result is treated as an "OR" of all the scopes.
        - 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: scopes
          in: query
          required: false
          type: string
          description:
            This parameter contains a comma-separated list of scopes.
            It was used in previous releases of the API and will be removed on 
            a future date.
      responses:
        '303':
          description:
            This the normal response to this API. It will immediately redirect
            the client to the location of the generated snapshot.
          headers:
            Location:
              description: URL to redirect to
              type: string

  /data/{snapshotId}:
    parameters:
      - name: snapshotId
        in: path
        required: true
        description: Unique identifier of a set of snapshot data
        type: string
    get:
      summary: Download snapshot data file
      description: 
        This is the API that is directed to by the "/snapshots" API. Users should
        not call it directly.
      produces:
        - application/json
        - application/transicator+protobuf
      responses:
        '200':
          description: "Snapshot data download"
          schema:
            $ref: '#/definitions/Snapshot'
            
  /scopes/{apidConfigID}:
    get:
      summary: Get list of scopes for a config
      description:
        This API downloads the list of scopes that a particular instance of the
        apid configuration requires. This API may be removed in a future release
        in favor of re-using the existing snapshot mechanism.
      parameters:
        - name: apidConfigID
          in: path
          required: true
          type: string
          description:
            The unique identifier of an API configuration object that the caller is
            authorized to see.
      responses:
        '200':
          description: Configuration downlaod
          schema:
            $ref: '#/definitions/Snapshot'
            
  /snapshotjobs:
    post:
      summary: Request a new snapshot job
      description: 
        This API is a placeholder for a future API that will allow a client to request
        asynchronous creation of a snapshot that may be consumed later.
      responses:
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"

  /snapshotjobs/{jobId}:
    get:
      summary: Get snapshot jobs info on status and metadata
      description: 
        This API is a placeholder for a future API that will allow a client to poll
        for the status of a previously-requested asynchronous snapshot.
      parameters:
        - name: jobId
          in: path
          required: true
          type: string
      responses:
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
            
  /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.
        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 "rows" property of a table.
    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
  Row:
    description: 
      A single row in the table. Keys are field names and values are
      Value objects.
    additionalProperties:
      $ref: '#/definitions/Value'
  Table:
    description: The snapshot of a single database table
    properties:
      name:
        description: The name of the table
        type: string
      rows:
        type: array
        items:
          $ref: '#/definitions/Row'
  Snapshot:
    description: A snapshot of the state of the database for a set of scopes.
    properties:
      snapshotInfo:
        description:
          The Postgres transaction IDs at the time when the snapshot was
          created. Should be passed as the "snaphot" parameter to the change
          server to result in a consistent set of changes.
        type: string
      timestamp:
        description: The time that the snapshot was generated, in Postgres format
        type: string
      tables:
        description: The tables represented in the snapshot
        type: array
        items:
          $ref: '#/definitions/Table'

  ErrorResponse:
    required:
      - message
    properties:
      message:
        type: string
        
  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".