core/src/main/resources/swagger.yaml

# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
# 
#   http://www.apache.org/licenses/LICENSE-2.0
# 
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.
swagger: '2.0'
info:
  title: Apache MetaModel Membrane
  description: Data Federation as a RESTful service.
  version: "1.0"
  contact:
    name: Apache MetaModel
    url: http://metamodel.apache.org
  license:
    name: Apache License, version 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
consumes:
  - application/json
produces:
  - application/json
paths:
  /:
    get:
      summary: Hello Membrane
      description: An endpoint that provides a confirmation that the system is operational
      responses:
        200:
          description: The system is operational
          schema:
            $ref: "#/definitions/helloResponse"
  /{tenant}:
    parameters:
      - name: tenant
        in: path
        type: string
        description: The tenant name
        required: true
    put:
      summary: Create new tenant
      responses:
        200:
          description: Tenant created
          schema:
            $ref: "#/definitions/putTenantResponse"
        409:
          description: Tenant already exist
          schema:
            $ref: "#/definitions/error"
    get:
      summary: Get tenant information
      description: Provides basic information about a tenant of the system
      responses:
        404:
          description: Tenant not found
          schema:
            $ref: "#/definitions/error"
        200:
          description: Tenant found
          schema:
            $ref: "#/definitions/getTenantResponse"
    delete:
      summary: Delete tenant
      description: Deletes a tenant from the system
      responses:
        200:
          description: Tenant deleted
          schema:
            $ref: "#/definitions/deleteTenantResponse"
        404:
          description: Tenant not found
          schema:
            $ref: "#/definitions/error"
  /{tenant}/{datasource}:
    parameters:
      - name: tenant
        in: path
        type: string
        description: The tenant name
        required: true
      - name: datasource
        in: path
        type: string
        description: The datasource name
        required: true
    get:
      responses:
        200:
          description: Datasource found
          schema:
            $ref: "#/definitions/getDatasourceResponse"
        404:
          description: Datasource not found
          schema:
            $ref: "#/definitions/error"
    put:
      parameters:
        - name: validate
          in: query
          description: Whether or not to validate the datasource properties and reject creating the datasource if it cannot be created.
          required: false
          type: boolean
          default: false
        - name: inputData
          in: body
          description: The definition of the datasource using properties. The same properties as normally applied in MetaModel factories (e.g. 'type', 'resource', 'url', 'driver-class' ,'hostname', 'port', 'catalog', 'database', 'username', 'port', 'table-defs') are used here.
          required: true
          schema:
            $ref: "#/definitions/putDatasourceRequest"
      responses:
        200:
          description: Datasource created
          schema:
            $ref: "#/definitions/getDatasourceResponse"
        400:
          description: Datasource validation failed
          schema:
            $ref: "#/definitions/error"
  /{tenant}/{datasource}/q:
    parameters:
      - name: tenant
        in: path
        type: string
        description: The tenant name
        required: true
      - name: datasource
        in: path
        type: string
        description: The datasource name
        required: true
    get:
      description: Executes a query on the datasource
      parameters:
      - name: sql
        in: query
        type: string
        description: The MetaModel-flavoured SQL query to execute
        required: true
      - name: offset
        in: query
        type: string
        description: An offset / first-row flag to set on the query
        required: false
      - name: limit
        in: query
        type: string
        description: A limit / max-rows flag to set on the query
        required: false
      responses:
        200:
          description: Query executed
          schema:
            $ref: "#/definitions/queryResponse"
        400:
          description: Failure while parsing query
          schema:
            $ref: "#/definitions/error"
        404:
          description: Datasource not found
          schema:
            $ref: "#/definitions/error"
        500:
          description: Failure while executing query
          schema:
            $ref: "#/definitions/error"
  /{tenant}/{datasource}/s/{schema}:
    parameters:
      - name: tenant
        in: path
        type: string
        description: The tenant name
        required: true
      - name: datasource
        in: path
        type: string
        description: The datasource name
        required: true
      - name: schema
        in: path
        type: string
        description: The schema name
        required: true
    get:
      responses:
        200:
          description: Schema found
          schema:
            $ref: "#/definitions/getSchemaResponse"
        404:
          description: Schema not found
          schema:
            $ref: "#/definitions/error"
  /{tenant}/{datasource}/s/{schema}/t/{table}:
    parameters:
      - name: tenant
        in: path
        type: string
        description: The tenant name
        required: true
      - name: datasource
        in: path
        type: string
        description: The datasource name
        required: true
      - name: schema
        in: path
        type: string
        description: The schema name
        required: true
      - name: table
        in: path
        type: string
        description: The table name
        required: true
    get:
      responses:
        200:
          description: Table found
          schema:
            $ref: "#/definitions/getTableResponse"
        404:
          description: Table not found
          schema:
            $ref: "#/definitions/error"
  /{tenant}/{datasource}/s/{schema}/t/{table}/d:
    parameters:
      - name: tenant
        in: path
        type: string
        description: The tenant name
        required: true
      - name: datasource
        in: path
        type: string
        description: The datasource name
        required: true
      - name: schema
        in: path
        type: string
        description: The schema name
        required: true
      - name: table
        in: path
        type: string
        description: The table name
        required: true
    get:
      description: Gets the data of the table
      responses:
        200:
          description: Query executed
          schema:
            $ref: "#/definitions/queryResponse"
        400:
          description: Failure while parsing query
          schema:
            $ref: "#/definitions/error"
        404:
          description: Table not found
          schema:
            $ref: "#/definitions/error"
        500:
          description: Failure while executing query
          schema:
            $ref: "#/definitions/error"
    post:
      description: Inserts data to the table
      parameters:
        - name: inputData
          in: body
          description: The data to insert
          required: true
          schema:
            $ref: "#/definitions/postDataRequest"
      responses:
        200:
          description: Data inserted
          schema:
            $ref: "#/definitions/postDataResponse"
        404:
          description: Table not found
          schema:
            $ref: "#/definitions/error"
  /{tenant}/{datasource}/s/{schema}/t/{table}/c/{column}:
    parameters:
      - name: tenant
        in: path
        type: string
        description: The tenant name
        required: true
      - name: datasource
        in: path
        type: string
        description: The datasource name
        required: true
      - name: schema
        in: path
        type: string
        description: The schema name
        required: true
      - name: table
        in: path
        type: string
        description: The table name
        required: true
      - name: column
        in: path
        type: string
        description: The column name
        required: true
    get:
      description: Gets information about a column
      responses:
        200:
          description: Query executed
          schema:
            $ref: "#/definitions/getColumnResponse"
        404:
          description: Column not found
          schema:
            $ref: "#/definitions/error"
definitions:
  queryResponse:
    description: Represents the result of a query - a dataset
    type: object
    properties:
      type:
        type: string
        description: The type of entity (dataset)
      headers:
        type: array
        description: The dataset header names
        items:
          type: string
      data:
        type: array
        description: The actual data returned by the query
        items:
          type: array
          items:
            type: object
  helloResponse:
    type: object
    properties:
      ping:
        type: string
        description: Should return 'pong!' when the system is operational
      application:
        type: string
        description: The name of the application running (Apache MetaModel Membrane)
      version:
        type: string
        description: The version of the application running
      server-time:
        type: object
        properties:
          timestamp:
            type: integer
            format: int64
            description: The server-time in timestamp format (millis since 1st of January 1970)
          iso8601:
            type: string
            description: The server-time in ISO-8601 format
      canonical-hostname:
        type: string
        description: The canonical hostname of the server
      open-api:
        type: object
        properties:
          spec:
            type: string
            format: uri
            description: Href for the Open API (fka. Swagger) specification that describes the service.
  getTenantResponse:
    type: object
    properties:
      type:
        type: string
        description: The type of entity (tenant)
      name:
        type: string
        description: The tenant name/identifier
      datasources:
        type: array
        items:
          type: object
          properties:
            name:
              type: string
              description: The name of the datasource
            uri:
              type: string
              format: uri
              description: A link to the datasource information
  putTenantResponse:
    type: object
    properties:
      type:
        type: string
        description: The type of entity (tenant)
      name:
        type: string
        description: The tenant name/identifier
  deleteTenantResponse:
    type: object
    properties:
      type:
        type: string
        description: The type of entity (tenant)
      name:
        type: string
        description: The tenant name/identifier
      deleted:
        type: boolean
        description: A confirmation boolean to indicate that the deletion is effectuated.
  postDataRequest:
    type: object
    properties:
      update:
        type: array
        items:
          type: object
          properties:
            values:
              type: object
              description: Record values to update where each key is expected to match a column name and each value is the value to put.
              example:
                favorite_java_library: Apache MetaModel
            where:
              type: array
              items:
                $ref: "#/definitions/whereCondition"
      delete:
        type: array
        items:
          type: object
          properties:
            where:
              type: array
              items:
                $ref: "#/definitions/whereCondition"
      insert:
        type: array
        items:
          description: A record to insert where each key is expected to match a column name and each value is the value to put.
          type: object
        example:
        - fullname: Jane Doe
          email_address: janedoe@gmail.com
          favourite_java_library: null
        - fullname: John Doe
          email_address: johndoe@gmail.com
          favourite_java_library: "MetaModel"
  whereCondition:
    type: object
    properties:
      column:
        type: string
      operator:
        $ref: "#/definitions/operator"
      operand:
        type: object
    example:
      column: fullname
      operator: like
      operand: "John%Doe"
  operator:
    type: string
    enum:
    - "eq"
    - "ne"
    - "gt"
    - "lt"
    - "like"
    - "not_like"
  postDataResponse:
    description: Represents the result of posting a data update to the records to a table
    type: object
    required:
      - status
    properties:
      status:
        type: string
        description: A confirmation 'ok' that the data updates went well.
      updated-rows:
        type: number
        format: int32
        description: The amount of updated records
      deleted-rows:
        type: number
        format: int32
        description: The amount of deleted records
      inserted-rows:
        type: number
        format: int32
        description: The amount of inserted records
      generated-keys:
        type: array
        description: An array of generated keys for the records, if any
        items:
          type: object
  putDatasourceRequest:
    type: object
    properties:
      type:
        type: string
        description: DataContext type (e.g. 'jdbc', 'csv' etc.)
    additionalProperties:
      type: string
  getDatasourceResponse:
    type: object
    properties:
      type:
        type: string
        description: The type of entity (datasource)
      name:
        type: string
        description: The datasource name
      tenant:
        type: string
        description: The tenant name
      updateable:
        type: boolean
        description: Is this datasource updateable?
      query_uri:
        type: string
        description: A link to the query endpoint for this datasource
        format: uri
      schemas:
        type: array
        description: The schemas of this datasource
        items:
          type: object
          properties:
            name:
              type: string
              description: The schema name
            uri:
              type: string
              description: A link to the schema information
              format: uri
  getSchemaResponse:
    type: object
    properties:
      type:
        type: string
        description: The type of entity (schema)
      name:
        type: string
        description: The schema name
      datasource:
        type: string
        description: The datasource name
      tenant:
        type: string
        description: The tenant name
      tables:
        type: array
        description: The names of the schema's tables
        items:
          type: object
          properties:
            name:
              type: string
              description: The table name
            uri:
              type: string
              description: A link to the table information
              format: uri
  getTableResponse:
    type: object
    properties:
      type:
        type: string
        description: The type of entity (table)
      name:
        type: string
        description: The table name
      schema:
        type: string
        description: The schema name
      datasource:
        type: string
        description: The datasource name
      tenant:
        type: string
        description: The tenant name
      columns:
        type: array
        description: The names of the table's columns
        items:
          type: object
          properties:
            name:
              type: string
              description: The column name
            uri:
              type: string
              description: A link to the column information
              format: uri
  getColumnResponse:
    type: object
    properties:
      type:
        type: string
        description: The type of entity (column)
      name:
        type: string
        description: The column name
      table:
        type: string
        description: The table name
      schema:
        type: string
        description: The schema name
      datasource:
        type: string
        description: The datasource name
      tenant:
        type: string
        description: The tenant name
      metadata:
        type: object
        description: Metadata about the column
        properties:
          number:
            type: integer
            description: The column number (0-based)
          size:
            type: integer
            description: The column size
          nullable:
            type: boolean
            description: Is the column nullable?
          primary-key:
            type: boolean
            description: Is the column a primary key?
          indexed:
            type: boolean
            description: Is the column indexed?
          column-type:
            type: string
            description: The column type (as interpreted/adapted by Apache MetaModel)
          native-type:
            type: string
            description: The native column type (as defined by the datasource itself)
          remarks:
            type: string
            description: Any remarks on the column
  error:
    description: Elaborates the error that occurred
    type: object
    properties:
      code:
        type: integer
        description: The HTTP status code
      message:
        type: string
        description: A humanly readable error message
      additional_details:
        type: object
        description: Any auxilary details to further elaborate the error