powerbipusher.swagger.yaml

openapi: 3.0.0
info:
  description: >-
    Power BI Data Pusher acts as a data pump to read multiple resultsets from
    database stored procedure and push them into multiple tables in Power BI
    Push Datasets. It provides 3 main functions:
  version: 1.0.0
  title: Power BI Data Pusher
  contact:
    name: PyWebApi
    url: 'https://github.com/DataBooster/PyWebApi'
  license:
    name: MIT
    url: 'https://github.com/DataBooster/PyWebApi/blob/master/LICENSE'

externalDocs:
  url: 'https://github.com/DataBooster/PyWebApi#powerbi-data-pusher'
  description: Wiki

tags:
  - name: Design-time
  - name: Deployment-time
  - name: Run-time

paths:
  /db_to_pbi.derive_bim:
    post:
      summary: "Derive Tabular Model from ResultSets of a Stored Procedure."
      operationId: derive_bim
      description: |-
        Generate and download a **Tabular Model (.bim file)** based on [ResultSets of a Stored Procedure](https://github.com/DataBooster/DbWebApi/wiki#http-response) as sample data for all tables to be created in a Power BI dataset.

        The first result set of the stored procedure must be used to indicate the corresponding Power BI table name for all subsequent result sets.
      tags:
        - Design-time
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/derive_bim'
        description: Payload
      responses:
        "200":
          description: Download the tabular model (.bim) file
          content:
            application/json:
              schema:
                type: object
                example: {"name": "PushDatasetName", "compatibilityLevel": 1520, "model": {"defaultPowerBIDataSourceVersion": "powerBI_V3", "tables": [{"name": "Table1", "columns": [{"name": "Columnl", "dataType": "dateTime"}], "partitions": [{"name": "None", "source": {"type": "m"}}]}]}}
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/ServerError'

  /db_to_pbi.deploy_dataset:
    post:
      summary: "Deploy a Tabular Model (.bim file) to Power BI workspace as a Push Dataset."
      operationId: deploy_dataset
      description: Create a pushable dataset (or update the metadata and schema for existing tables) in Power BI Service by a Tabular Model (.bim) file.
      tags:
        - Deployment-time
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deploy_dataset'
        description: Payload
      responses:
        "200":
          description: Return the dataset_id that just been created or updated.
          content:
            application/json:
              schema:
                type: string
                format: uuid
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/ServerError'
        
  /db_to_pbi.push_data:
    post:
      summary: "Push new data to a Power BI Push Dataset."
      operationId: push_data
      description: |-
        Push all ResultSets of a Stored Procedure - data for multiple tables into a Power BI Push Dataset.

        The first result set of the stored procedure must be used to indicate the corresponding Power BI table name in Push Dataset for all subsequent result sets, and (optional) the Sequence Number for the corresponding table if you need to enable the **X-PowerBI-PushData-SequenceNumber** feature - a Power BI build-in mechanism to guarantee which rows have been successfully pushed.
      tags:
        - Run-time
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/push_data'
        description: Payload
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                example: null
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/ServerError'

  /db_to_pbi.get_seq_num:
    post:
      summary: "Get all current sequence numbers of specified (or all) tables."
      operationId: get_seq_num
      description: Discover the current sequence numbers which are stored with the specified list of tables in a Power BI Push Dataset.
      tags:
        - Run-time
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/table_list'
        description: Payload
      responses:
        "200":
          description: Return a list of table names with associated sequence numbers.
          content:
            application/json:
              schema:
                type: object
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/ServerError'
  
  /db_to_pbi.truncate:
    post:
      summary: "Truncate specified (or all) tables."
      operationId: truncate
      description: Removes all rows from specified (or all) tables in a Power BI Push Dataset.
      tags:
        - Run-time
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/table_list'
        description: Payload
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
        "401":
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/ServerError'

components:

  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error-response'
    ServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error-response'

  schemas:
    _sp-base:
      type: object
      required:
        - sp_url
        - sp_args
      properties:
        sp_url:
          type: string
          format: url
          example: http://localhost/dbwebapi/oradev/my_app/schema.package_for_pbi.test_dataset/json?NamingCase=Pascal
          description: URL of the stored procedure
        sp_args:
          type: object
          default: {}
          description: Payload of the stored procedure
      description: <https://github.com/DataBooster/DbWebApi/wiki>
        
    derive_bim:
      allOf:
        - $ref: '#/components/schemas/_sp-base'
        - type: object
          properties:
            dataset_name: &dataset_name_sp
              type: string
              default: (same as the stored procedure name)
              example: PushDatasetTest1
              description: The name of Push Dataset. If this argument is omitted, the name of the stored procedure will be passed as the name of the dataset.
            timeout: &timeout
              type: number
              default: &timeout_default 180
              example: *timeout_default
              description: Stop waiting for the stored procedure's response after a given number of seconds.
          description: derive_bim request payload

    deploy_dataset:
      type: object
      required:
        - model_bim
        - dataset_name
      properties:
        model_bim:
          type: string
          example: \\network_server\share_folder\test_model.bim
          description: This argument can be a JSON object, a JSON string, or a network path of the .bim file that the server can read.
        dataset_name: &dataset_name
          type: string
          example: PushDatasetTest1
          description: The name of Power BI Push Dataset.
        workspace: &workspace
          type: string
          default: null
          example: Power BI Workspace1
          description: Power BI workspace
      description: deploy_dataset request payload

    push_data:
      allOf:
        - $ref: '#/components/schemas/_sp-base'
        - type: object
          required:
            - dataset_name
          properties:
            dataset_name: *dataset_name_sp
            workspace: *workspace
            timeout: *timeout
          description: push_data request payload

    table_list:
      type: object
      required:
        - table_names
        - dataset_name
      properties:
        table_names:
          type: array
          items:
            type: string
            description: table name
          example: null
          description: An array of table names. *(null indicates all tables in the Power BI Push Dataset)*
        dataset_name: *dataset_name
        workspace: *workspace

    error-response:
      type: object
      required:
        - ExceptionMessage
      properties:
        ExceptionMessage:
          type: string
        ExceptionType:
          type: string
        StackTrace:
          type: string

servers:
  - description: (Please update the local-test base URL to your actual path)
    url: http://localhost/PyWebApi/pys/test_app/samples/powerbipusher