PingCAP Data Source API

openapi: 3.2.0
info:
  title: TiDB Cloud Data Service OPEN Data Source API
  description: '# Overview


    The TiDB Cloud Data Service API provides a RESTful interface for programmatically managing administrative objects within the TiDB Cloud Data Service.'
  version: v1beta1
servers:
- url: https://dataservice.tidbapi.com
tags:
- name: Data Source
  description: Create, get, delete, and list data sources of a Data App.
paths:
  /v1beta1/dataApps/{dataAppId}/dataSources:
    get:
      x-code-samples:
      - lang: Curl
        source: "curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request GET \\\n --url 'https://dataservice.tidbapi.com/v1beta1/dataApps/{dataAppId}/dataSources?pageSize=5'"
      summary: List all data sources in a Data App
      operationId: DataSource_ListDataSources
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1ListDataSourcesResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: dataAppId
        description: The ID of the Data App. You can get the ID from the response of [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps).
        in: path
        required: true
        schema:
          type: string
      - name: pageSize
        description: The maximum number of items to return. If it is not set or set to `0`, the default value `100` will be used.
        in: query
        required: false
        schema:
          type: integer
          format: int32
          default: 100
          maximum: 100
          minimum: 1
      - name: pageToken
        description: The identifier of the current page, used to retrieve the next page of results. You can get this value from the `nextPageToken` field in the previous response. To access the first page of data, omit this field.
        in: query
        required: false
        schema:
          type: string
      tags:
      - Data Source
    post:
      x-code-samples:
      - lang: Curl
        source: "curl --digest \\\n  --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  --request POST \\\n  --url 'https://dataservice.tidbapi.com/v1beta1/dataApps/{dataAppId}/dataSources' \\\n  --header 'Content-Type: application/json' \\\n  --data-raw '{\n    \"clusterId\": \"{clusterId}\"\n  }'"
      summary: Create a data source for a Data App
      description: With this endpoint, you can link a cluster to a Data App. Then, the Data App can access and manipulate data in the cluster.
      operationId: DataSource_CreateDataSource
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1DataSource'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: dataAppId
        description: The ID of the Data App. You can get the ID from the response of [List all Data Apps in a project](#tag/Data-App/operation/DataApp_ListDataApps).
        in: path
        required: true
        schema:
          type: string
      tags:
      - Data Source
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                clusterId:
                  type: string
                  description: The ID of the cluster that needs to be linked to the Data App.
              required:
              - clusterId
        required: true
  /v1beta1/dataApps/{dataAppId}/dataSources/{clusterId}:
    get:
      x-code-samples:
      - lang: Curl
        source: "curl --digest \\\n  --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  --request GET \\\n  --url 'https://dataservice.tidbapi.com/v1beta1/dataApps/{dataAppId}/dataSources/{clusterId}'"
      summary: Get a data source by ID
      operationId: DataSource_GetDataSource
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1DataSource'
        default:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: clusterId
        description: The ID of the cluster that is linked to the Data App.
        in: path
        required: true
        schema:
          type: string
      tags:
      - Data Source
    delete:
      x-code-samples:
      - lang: Curl
        source: "curl --digest \\\n  --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n  --request DELETE \\\n  --url 'https://dataservice.tidbapi.com/v1beta1/dataApps/{dataAppId}/dataSources/{clusterId}'"
      summary: Delete a data source for a Data App
      description: With this endpoint, you can unlink a cluster from a Data App. Then, the existing endpoints in the Data App cannot access the cluster anymore.
      operationId: DataSource_DeleteDataSource
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties: {}
        default:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: clusterId
        description: The ID of the cluster that is linked to the Data App.
        in: path
        required: true
        schema:
          type: string
      tags:
      - Data Source
components:
  schemas:
    v1beta1DataSource:
      type: object
      properties:
        clusterId:
          type: string
          description: The IDs of the clusters that the Data App's data source is linked to.
        name:
          type: string
          description: The unique identifier for the data source, which is generated by the API and follows the format `dataApps/{dataAppId}/dataSources/{clusterId}`.
        clusterDisplay:
          type: string
          description: The name of the cluster.
        clusterType:
          type: string
          description: 'The cluster type:

            - `"Serverless"`: a [TiDB Cloud Starter](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-serverless) cluster

            - `"Dedicated"`: a [TiDB Cloud Dedicated](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-dedicated) cluster'
        clusterProvider:
          type: string
          description: 'The cloud provider on which your TiDB cluster is hosted.

            - `"aws"`: the Amazon Web Services cloud provider

            - `"gcp"`: the Google Cloud cloud provider'
          example: AWS
        clusterRegion:
          type: string
          description: The region code of the cluster.
          example: us-east-1
        clusterRegionDisplay:
          type: string
          description: The name of the cluster region as shown in the TiDB Cloud console.
          example: N. Virginia (us-east-1)
        createdAt:
          type: string
          description: 'The timestamp when the Data App was created. The time format follows the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard. For example: `"2023-06-03T06:52:08Z"`.'
    protobufAny:
      type: object
      properties:
        '@type':
          type: string
      additionalProperties: {}
    rpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/protobufAny'
    v1beta1ListDataSourcesResponse:
      type: object
      properties:
        dataSources:
          type: array
          items:
            $ref: '#/components/schemas/v1beta1DataSource'
          description: The items of data sources in the Data App.
        nextPageToken:
          type: string
          description: The token to retrieve the next page of results.
      title: Response for ListDataSources
x-tagGroups:
- name: Endpoints
  tags:
  - Data App
  - Data Source
  - Endpoint
  - Deployment
  - Data API Key
  - OpenAPI Specification