swagger.yaml

swagger: '2.0'
info:
  title: Building blocks of REPL and CRUD module
  description: |
    Assumes you have read
    [APID Core](https://docs.google.com/a/apigee.com/document/d/15-HvWdv-JGRk5rKDK5DLjr0qEqe8lwy18AQRQqRlO-I/edit?usp=sharing),
    [Apigee Edge API style guide](https://docs.google.com/document/d/1iwzeSdQqsDnhapQarQKs9pK_8vQUdnI91RNiwHeLv94/)
  version: '0.9'
  contact:
    name: 'Apigee Inc.'
    email: support@apigee.com
    url: 'https://www.apigee.com/'
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
basePath: /apid
consumes:
  - application/json
  - application/x-www-form-urlencoded
produces:
  - application/json
paths:
  /db: # PATH
    get: # VERB
      summary: describeService() - Get description of this service.
      operationId: describeService
      description: return swagger.json for this service.
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/ServiceResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
  '/db/_schema/{table_name}': # PATH
    parameters:
      - name: table_name
        description: Name of the table to perform operations on.
        type: string
        in: path
        required: true
    get: # VERB
      tags:
        - schema
      summary: describeDbTable() - Retrieve table definition for the given table.
      operationId: describeDbTable
      parameters:
        - name: refresh
          description: Refresh any cached copy of the schema.
          type: boolean
          in: query
      responses:
        '200':
          description: Table Schema
          schema:
            $ref: '#/definitions/SchemaResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      description: 'This describes the table, its fields and relations to other tables.'
    post: # VERB
      tags:
        - schema
      summary: createDbTable() - Create a table with the given properties and fields.
      operationId: createDbTable
      parameters:
        - name: schema
          description: Array of table properties and fields definitions.
          schema:
            $ref: '#/definitions/TableSchema'
          in: body
          required: true
      responses:
        '201':
          description: Success
          schema:
            $ref: '#/definitions/Success'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      description: >-
        Post data should be an array of field properties for a single record or
        an array of fields.
    delete: # VERB
      tags:
        - schema
      summary: deleteDbTable() - Delete (aka drop) the given table.
      operationId: deleteDbTable
      parameters: []
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/Success'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
      description: 'Careful, this drops the database table and all of its contents.'
  /db/_table: # PATH
    get: # VERB
      tags: [table, getDbTables]
      summary: getDbTables() - List all Tables
      operationId: getDbTables
      description: Return a list of the table names.
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/TablesResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
  '/db/_table/{table_name}': # PATH
    parameters:
      - name: table_name
        description: Name of the table to perform operations on.
        type: string
        in: path
        required: true
    get: # VERB
      tags: [table, get, record, getDbRecords]
      summary: getDbRecords() - Retrieve one or more records.
      operationId: getDbRecords
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: fields
          type: array
          collectionFormat: csv
          items:
            type: string
          in: query
          description: >-
            Comma-delimited list of properties to be returned for each resource,
            "*" returns all properties. If as_list, use this to override the
            default identifier.
        - name: limit
          type: integer
          in: query
          description: Set to limit the filter results.
        - name: offset
          type: integer
          format: int64
          in: query
          description: Set to offset the filter results to a particular record count.
        - name: ids
          type: array
          collectionFormat: csv
          items:
            type: integer
            format: int64
          in: query
          description: Comma-delimited list of the identifiers of the records to retrieve.
        - name: id_field
          type: array
          collectionFormat: csv
          items:
            type: string
          in: query
          description: >-
            name of the field used as identifier.
      responses:
        '200':
          description: Records
          schema:
            $ref: '#/definitions/RecordsResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
    post: # VERB
      tags: [table, post, record, createDbRecords]
      summary: createDbRecords() - Create one or more records.
      operationId: createDbRecords
      description: >-
        Posted data should be an array of records wrapped in a <b>record</b>
        element. By default, only the id property of the record is returned
        on success. Use fields parameter to return more info.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: body
          description: Data containing name-value pairs of records to create.
          in: body
          schema:
            $ref: '#/definitions/BodyRecord'
          required: true
        - name: fields
          type: array
          collectionFormat: csv
          items:
            type: string
          in: query
          description: >-
            Comma-delimited list of properties to be returned for each resource,
            "*" returns all properties. If as_list, use this to override the
            default identifier.
        - name: id_field
          type: string
          in: query
          description: >-
            Name of the field used as identifier.
      responses:
        '201':
          description: IdsResponse
          schema:
            $ref: '#/definitions/IdsResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
    patch: # VERB
      tags: [table, patch, record, updateDbRecords]
      summary: updateDbRecords() - Update (patch) one or more records.
      operationId: updateDbRecords
      description: >-
        Post data should be an array of records containing at least the
        identifying fields for each record. Posted body should be a single
        record with name-value pairs to update wrapped in a record
        tag. Ids can be included via URL parameter or included in the
        posted body. Filter can be included via URL parameter or included
        in the posted body. By default, only the id property of the record
        is returned on success. Use fields parameter to return more info.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: body
          description: >-
            a single record, with the item Records being an array of objects.
            each object contains item Keys, a list of keys; and item Values,
            a list of values.
          schema:
            $ref: '#/definitions/BodyRecord'
          in: body
          required: true
        - name: fields
          type: array
          collectionFormat: csv
          items:
            type: string
          in: query
          description: >-
            Comma-delimited list of properties to be returned for each resource,
            "*" returns all properties. If as_list, use this to override the
            default identifier.
        - name: ids
          type: array
          collectionFormat: csv
          items:
            type: string
          in: query
          description: Comma-delimited list of the identifiers of the records to retrieve.
        - name: id_field
          type: array
          collectionFormat: csv
          items:
            type: string
          in: query
          description: >-
            Name of field used as identifier.
      responses:
        '200':
          description: number of changed records
          schema:
            $ref: '#/definitions/NumChangedResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
    delete: # VERB
      tags: [table, delete, record, deleteDbRecords]
      summary: deleteDbRecords() - Delete one or more records.
      operationId: deleteDbRecords
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: fields
          type: array
          collectionFormat: csv
          items:
            type: string
          in: query
          description: >-
            Comma-delimited list of properties to be returned for each resource,
            "*" returns all properties. If as_list, use this to override the
            default identifier.
        - name: ids
          type: array
          collectionFormat: csv
          items:
            type: integer
            format: int64
          in: query
          description: Comma-delimited list of the identifiers of the records to delete.
        - name: id_field
          type: array
          collectionFormat: csv
          items:
            type: string
          in: query
          description: >-
            Name of the field used as identifier.
      responses:
        '200':
          description: Records
          schema:
            $ref: '#/definitions/NumChangedResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
  '/db/_table/{table_name}/{id}': # PATH
    parameters:
      - name: id
        description: Identifier of the record to retrieve.
        type: string
        in: path
        required: true
      - name: table_name
        description: Name of the table to perform operations on.
        type: string
        in: path
        required: true
    get: # VERB
      tags: [table, get, record, getDbRecord]
      summary: getDbRecord() - Retrieve one record by identifier.
      operationId: getDbRecord
      description: >-
        Use the fields parameter to limit properties that are returned.
        By default, all fields are returned.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: fields
          type: array
          collectionFormat: csv
          items:
            type: string
          in: query
          description: >-
            Comma-delimited list of properties to be returned for each resource,
            "*" returns all properties. If as_list, use this to override the
            default identifier.
        - name: id_field
          type: array
          collectionFormat: csv
          items:
            type: string
          in: query
          description: >-
            Comma-delimited list of the fields used as identifiers, used to
            override defaults or provide identifiers when none are provisioned.
      responses:
        '200':
          description: Record
          schema:
            $ref: '#/definitions/RecordsResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
    patch: # VERB
      tags: [table, patch, record, updateDbRecord]
      summary: updateDbRecord() - Update (patch) one record by identifier.
      operationId: updateDbRecord
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: body
          description: Data containing name-value pairs of the fields to update.
          schema:
            $ref: '#/definitions/KVRecord'
          in: body
          required: true
        - name: id_field
          type: array
          collectionFormat: csv
          items:
            type: string
          in: query
          description: >-
            Name of the id field to use.
      responses:
        '200':
          description: Record
          schema:
            $ref: '#/definitions/NumChangedResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
    delete: # VERB
      tags: [table, delete, record, deleteDbRecord]
      summary: deleteDbRecord() - Delete one record by identifier.
      operationId: deleteDbRecord
      description: >-
        Use the <b>fields</b> parameter to return more deleted properties. By
        default, the id is returned.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: fields
          type: array
          collectionFormat: csv
          items:
            type: string
          in: query
          description: >-
            Comma-delimited list of properties to be returned for each resource,
            "*" returns all properties. If as_list, use this to override the
            default identifier.
        - name: id_field
          type: array
          collectionFormat: csv
          items:
            type: string
          in: query
          description: >-
            Name of the field used as identifier.
      responses:
        '200':
          description: Record
          schema:
            $ref: '#/definitions/NumChangedResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/ErrorResponse'
definitions:
  Success:
    type: object
    properties:
      success:
        type: boolean
        description: 'True when API call was successful, false or error otherwise.'
  ErrorResponse:
    type: object
    properties:
      code:
        type: integer
        format: int64
        description: Error code.
      message:
        type: string
        description: String description of the error.
      kind:
        type: string
  ServiceResponse:
    type: object
    properties:
      description:
        type: string
      kind:
        type: string
      self:
        type: string
  SchemaResponse:
    type: object
    properties:
      name:
        type: string
        description: Identifier of the resource.
      kind:
        type: string
      self:
        type: string
  TableSchema:
    type: object
    properties:
      fields:
        type: array
        description: An array of available fields in each record.
        items:
          $ref: '#/definitions/FieldSchema'
  FieldSchema:
    type: object
    properties:
      name:
        type: string
        description: The API name of the field.
      db_type:
        type: string
        description: The native database type used for this field.
      length:
        type: integer
        format: int64
        description: >-
          The maximum length allowed (in characters for string, displayed for
          numbers).
      allow_null:
        type: boolean
        description: Is null allowed as a value.
      auto_increment:
        type: boolean
        description: Does the integer field value increment upon new record creation.
      is_primary_key:
        type: boolean
        description: Is this field used as/part of the primary key.
  TablesResponse:
    type: object
    properties:
      resource:
        type: array
        description: Array of resources available to this path.
        items:
          type: string
      kind:
        type: string
      self:
        type: string
  KVRecord:
    type: object
    properties:
      keys:
        type: array
        items:
          type: string
      values:
        type: array
        items:
          type: string
  KVResponse:
    type: object
    properties:
      keys:
        type: array
        items:
          type: string
      values:
        type: array
        items:
          type: string
      kind:
        type: string
      self:
        type: string
  BodyRecord:
    type: object
    properties:
      Records:
        type: array
        description: Array of keynames.
        items:
          $ref: '#/definitions/KVRecord'
  NumChangedResponse:
    type: object
    properties:
      numChanged:
        type: integer
        format: int64
      kind:
        type: string
  IdsResponse:
    type: object
    properties:
      ids:
        type: array
        description: array of ids
        items:
          type: integer
          format: int64
      kind:
        type: string
  RecordsResponse:
    type: object
    properties:
      resource:
        type: array
        description: Array of system user records.
        items:
          $ref: '#/definitions/KVResponse'