swagger: '2.0'
info:
  description: >-
    DATA Tables API

  version: "5.0"
  title: DATA Tables
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
basePath: /index.php/api/
tags:
  - name: Tables
    description: Data Tables
x-tagGroups:
  - name: Tables 
    tags:
      - Tables
schemes:
  - http
  - https
paths:
  /tables:
      get:
        tags:
          - Tables
        summary: List all tables
        description: Returns a list of all tables
        operationId: listTables
        consumes:
          - application/json
        produces:
          - application/json
        responses:
          '200':
            description: successful operation            
        security:
          - ApiKeyAuth: []
  /tables/info/{dbId}/{tableId}:
      get:
        tags:
          - Tables
        summary: Get table info
        description: Returns table definition
        operationId: tableInfo
        consumes:
          - application/json
        produces:
          - application/json
        parameters:
          - in: "path"
            name: "dbId"
            type: string
            format: string
            required: true
          - in: "path"
            name: "tableId"
            type: string
            format: string
            required: true
        responses:
          '200':
            description: successful operation
            schema:
              $ref: "#/definitions/Table"
        security:
          - ApiKeyAuth: []
  /tables/data/{dbId}/{tableId}:
      get:
        tags:
          - Tables
        summary: Get table data
        description: Get table data
        operationId: getTableData
        consumes:
          - application/json
        produces:
          - application/json
        parameters:
          - in: "path"
            name: "dbId"
            type: string
            format: string
            required: true
          - in: "path"
            name: "tableId"
            type: string
            format: string
            required: true
          - in: "path"
            name: "limit"
            type: integer
            required: true
          - in: "path"
            name: "offset"
            type: integer
            required: false
          - in: "query"
            name: "indicator"
            type: integer
            required: false      
          - in: "query"
            name: "<name of feature>"
            type: string
            required: false 
          - in: "query"
            name: "fields"
            type: string
            description: A comma seperated list of fields to output
            required: false                      
          - in: "query"
            name: "format"
            type: string
            description: Output format - json, csv
            required: false

        responses:
          '200':
            description: successful operation
        security:
          - ApiKeyAuth: []       
  
  /tables/create_table:
      post:
        tags:
          - Tables
        summary: Create new table
        description: Create new table type
        operationId: createTableType
        consumes:
          - application/json
        produces:
          - application/json
        parameters:
          - in: "body"
            name: "body"
            required: true
            schema:
              $ref: 'table_type-schema.json'
        responses:
          '200':
            description: successful operation
            schema:
              $ref: 'table_type-schema.json'
        security:
          - ApiKeyAuth: [] 
                   
  /tables/upload:
      post:
        tags:
          - Tables
        summary: Upload CSV
        description: Upload CSV file. By default, it will replace an existing table or create a new one. To append data to an existing table, set `append` to `true`
        operationId: uploadCsv
        consumes:
          - application/json
        produces:
          - application/json
        parameters:
          - in: "path"
            name: "dbId"
            description: Database ID
            type: string
            format: string
            required: true
          - in: "path"
            name: "tableId"
            description: Table ID
            type: string
            format: string
            required: true  
          - in: "query"
            name: "append"
            description: Append data to existing table
            type: boolean
            required: false
          - in: "formData"
            name: "file"
            type: file
            description: "CSV file"
            required: true
          - in: "formData"
            name: "delimiter"
            type: string
            description: "CSV delimiter character - default is `,`. For tabs, use `tab`"
        responses:
          '200':
            description: successful operation
        security:
          - ApiKeyAuth: []  
  
  /tables/insert/{dbId}/{tableId}:      
        post:
          tags:
            - Tables
          summary: Insert table data
          description: Insert rows of data as JSON object
          operationId: postTable
          consumes:
            - application/json
          produces:
            - application/json
          parameters:
            - in: "path"
              name: "dbId"
              type: string
              format: string
              required: true
            - in: "path"
              name: "tableId"
              type: string
              format: string
              required: true
            - in: "body"
              name: "body"
              description: "Table rows as JSON object"
              required: true
              schema:
                type: object
          responses:
            '200':
              description: successful operation
          security:
            - ApiKeyAuth: []  


  /tables/indexes/{dbId}/{tableId}:
      get:
        tags:
          - Tables
        summary: Get table indexes
        description: Returns a list of table indexes
        operationId: tableIndexes
        consumes:
          - application/json
        produces:
          - application/json
        parameters:
          - in: "path"
            name: "dbId"
            type: string
            format: string
            required: true
          - in: "path"
            name: "tableId"
            type: string
            format: string
            required: true
        responses:
          '200':
            description: successful operation
        security:
          - ApiKeyAuth: []   
      post:
        tags:
          - Tables
        summary: Create table index
        description: Create a new index
        operationId: tableIndex
        consumes:
          - application/json
        produces:
          - application/json
        parameters:
          - in: "path"
            name: "dbId"
            type: string
            format: string
            required: true
          - in: "path"
            name: "tableId"
            type: string
            format: string
            required: true
          - in: body
            name: index_fields
            description: A comma seperated list of fields for creating new index e.g. `state, district, urbrur`
            schema:
              type: object
              required:
                - index_fields
              properties:
                index_fields:
                  type: string                
        responses:
          '200':
            description: successful operation
        security:
          - ApiKeyAuth: []
      delete:
        tags:
          - Tables
        summary: Delete table index
        description: Delete a table index - `tables/indexes/{dbId}/{tableId}/{indexName}`
        operationId: tableIndexesDelete
        consumes:
          - application/json
        produces:
          - application/json
        parameters:
          - in: "path"
            name: "dbId"
            type: string
            format: string
            required: true
          - in: "path"
            name: "tableId"
            type: string
            format: string
            required: true
          - in: "path"
            name: "indexName"
            type: string
            format: string
            required: true  
        responses:
          '200':
            description: successful operation
        security:
          - ApiKeyAuth: []  
  /tables/text_index/{dbId}/{tableId}:
      post:
        tags:
          - Tables
        summary: Create fulltext index
        description: Create a fulltext index for table. Only one text index can be created per table.
        operationId: tableTextIndex
        consumes:
          - application/json
        produces:
          - application/json
        parameters:
          - in: "path"
            name: "dbId"
            type: string
            format: string
            required: true
          - in: "path"
            name: "tableId"
            type: string
            format: string
            required: true
          - in: body
            name: index_fields
            description: A comma seperated list of fields for creating new index e.g. `state, district, urbrur`
            schema:
              type: object
              required:
                - index_fields
              properties:
                index_fields:
                  type: string                
        responses:
          '200':
            description: successful operation
        security:
          - ApiKeyAuth: []
  
  /tables/attach_to_study:
      post:
        tags:
          - Tables
        summary: Attach table to a study
        description: Attach table to a study
        operationId: tableAttachToStudy
        consumes:
          - application/json
        produces:
          - application/json
        parameters:
          - in: body
            schema:
              type: object
              required:
                - db_id
                - table_id
                - sid
                - title
              properties:
                db_id:
                  type: string                
                table_id:
                  type: string
                sid:
                  type: string
                  description: Study ID
                title:
                  type: string
                  description: Dataset title
        responses:
          '200':
            description: successful operation
        security:
          - ApiKeyAuth: []  
  /tables/detach_from_study:
      post:
        tags:
          - Tables
        summary: Remove table from study
        description: Dettach table from study
        operationId: tableDettachFromStudy
        consumes:
          - application/json
        produces:
          - application/json
        parameters:
          - in: body
            schema:
              type: object
              required:
                - db_id
                - table_id
                - sid
                - title
              properties:
                db_id:
                  type: string                
                table_id:
                  type: string
                sid:
                  type: string
                  description: Study ID
                title:
                  type: string
                  description: Dataset title
        responses:
          '200':
            description: successful operation
        security:
          - ApiKeyAuth: []
  /tables/list_by_study/{sid}:
      post:
        tags:
          - Tables
        summary: List tables by study
        description: Get a list of tables attached to a study
        operationId: tableListByStudy
        consumes:
          - application/json
        produces:
          - application/json
        parameters:
          - in: url
            name: sid
            type: string
            description: Study ID
            required: true
        responses:
          '200':
            description: successful operation
        security:
          - ApiKeyAuth: []    
  
###############################################################
securityDefinitions:
  ApiKeyAuth:
    type: apiKey
    name: X-API-KEY
    in: header
definitions:
  CsvImport:
    type: object
    properties:
      db_id:
        type: string
      table_id:
        type: string
      file_path:
        type: string
        description: File name for uploaded CSV file
        example: "table-name.csv"
      delimiter:
        type: string  
        description: CSV delimiter - default is Comma(,)
        example: "tab"
    required:
      - db_id
      - table_id
      - file_path 
    xml:
      name: CsvImport

  Table:
    type: object
    properties:
      id:
        type: integer
        format: int64
        readOnly: true
      table_id:
        type: string
        required: true
        title: "Table unique IDNo"        
      title:
        type: string 
        required: true
        description: Table Title 
      description:
        required: true
        type: string 
        description: A short description
      unit_observation:
        type: string 
        required: true
        description: Unit of observation
      features:
        type: array
        required: true
        description: Features
        items:
          type: string
    xml:
      name: table
      
  
  ApiResponse:
    type: object
    properties:
      code:
        type: integer
        format: int32
      type:
        type: string
      message:
        type: string