PingCAP Endpoint API

openapi: 3.2.0
info:
  title: TiDB Cloud Data Service OPEN Endpoint 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: Endpoint
  description: Create, get, delete, list, and test endpoints of a Data App.
paths:
  /v1beta1/dataApps/{dataAppId}/endpoints:
    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}/endpoints?pageSize=5'"
      summary: List all endpoints in a Data App
      operationId: Endpoint_ListEndpoints
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1ListEndpointsResponse'
        '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:
      - Endpoint
    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}/endpoints' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n    \"displayName\": \"/v1/hello\", \n    \"description\": \"/v1/hello endpoint\", \n    \"path\": \"/v1/hello\", \n    \"method\": \"GET\", \n    \"clusterId\": \"{clusterId}\", \n    \"settings\": {\n      \"timeout\": 30000, \n      \"rowLimit\": 2000, \n      \"paginationEnabled\": false, \n      \"cacheEnabled\": false\n    }, \n    \"tag\": \"Default\", \n    \"sqlTemplate\": \"select 'Hello World';\" \n  }'"
      summary: Create an endpoint for a Data App
      operationId: Endpoint_CreateEndpoint
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1EndpointRes'
        '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:
      - Endpoint
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1beta1Endpoint'
        description: Endpoint
        required: true
  /v1beta1/dataApps/{endpoint.name}:
    patch:
      x-code-samples:
      - lang: Curl
        source: "curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request PATCH \\\n --url 'https://dataservice.tidbapi.com/v1beta1/{endpoint.name}' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n    \"displayName\": \"/v2/hello\", \n    \"description\": \"/v2/hello endpoint\", \n    \"path\": \"/v2/hello\", \n    \"method\": \"GET\", \n    \"clusterId\": \"{clusterId}\", \n    \"settings\": {\n      \"timeout\": 30000, \n      \"rowLimit\": 2000, \n      \"paginationEnabled\": false, \n      \"cacheEnabled\": false\n    }, \n    \"tag\": \"V2\", \n    \"sqlTemplate\": \"select 'Hello World New';\" \n  }'"
      summary: Update an endpoint for a Data App
      operationId: Endpoint_UpdateEndpoint
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1EndpointRes'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: endpoint.name
        description: 'The unique identifier for the endpoint. For example: `dataApps/dataapp-yxNzAuFP/endpoints/1874778`. You can get the value from the response of [List all endpoints in a Data App](#tag/Endpoint/operation/Endpoint_ListEndpoints).'
        in: path
        required: true
        schema:
          type: string
          pattern: dataApps/[^/]+/endpoints/[^/]+
      tags:
      - Endpoint
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1beta1Endpoint'
        description: 'To update an endpoint, specify the following fields as needed:'
        required: true
    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/{endpoint.name}'"
      summary: Get an endpoint for a Data App
      operationId: Endpoint_GetEndpoint
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1EndpointRes'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: endpoint.name
        description: 'The unique identifier for the endpoint. For example: `dataApps/dataapp-yxNzAuFP/endpoints/1874778`. You can get the value from the response of [List all endpoints in a Data App](#tag/Endpoint/operation/Endpoint_ListEndpoints).'
        in: path
        required: true
        schema:
          type: string
          pattern: dataApps/[^/]+/endpoints/[^/]+
      tags:
      - Endpoint
    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/{endpoint.name}'"
      summary: Delete an endpoint for a Data App
      description: Before you delete an endpoint, make sure that the endpoint is not online. Otherwise, the endpoint cannot be deleted.
      operationId: Endpoint_DeleteEndpoint
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: endpoint.name
        description: 'The unique identifier for the endpoint. For example: `dataApps/dataapp-yxNzAuFP/endpoints/1874778`. You can get the value from the response of [List all endpoints in a Data App](#tag/Endpoint/operation/Endpoint_ListEndpoints).'
        in: path
        required: true
        schema:
          type: string
          pattern: dataApps/[^/]+/endpoints/[^/]+
      tags:
      - Endpoint
  /v1beta1/{endpoint.name}/test:
    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/{endpoint.name}/test' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\n    \"args\": [\n      {\n       \"items\": {}\n      }\n    ] \n  }'"
      summary: Test an endpoint for a Data App
      operationId: Endpoint_TestEndpoint
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1TestEndpointResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: endpoint.name
        description: 'The unique identifier for the endpoint. For example: `dataApps/dataapp-yxNzAuFP/endpoints/1874778`. You can get the value from the response of [List all endpoints in a Data App](#tag/Endpoint/operation/Endpoint_ListEndpoints).'
        in: path
        required: true
        schema:
          type: string
          pattern: dataApps/[^/]+/endpoints/[^/]+
      tags:
      - Endpoint
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                args:
                  type: array
                  items:
                    $ref: '#/components/schemas/v1beta1EndpointArgs'
              required:
              - args
        description: The parameter values used for testing the endpoint.
        required: true
components:
  schemas:
    TestEndpointResponseColumn:
      type: object
      properties:
        col:
          type: string
          description: The column name of the requested data table.
        dataType:
          type: string
          description: The column type of the requested data table.
        nullable:
          type: boolean
          description: Whether the column of the requested data table supports null values.
    v1beta1EndpointSettings:
      type: object
      properties:
        timeout:
          type: integer
          format: int32
          description: The user-defined timeout for the endpoint in milliseconds.
          minimum: 1
          maximum: 60000
        rowLimit:
          type: integer
          format: int32
          description: The maximum number of rows that the endpoint can operate or return.
          minimum: 1
          maximum: 2000
        paginationEnabled:
          type: boolean
          description: Controls whether to enable the pagination for the results returned by the `GET` request. When pagination is enabled, you can paginate the results by specifying `page` and `page_size` as query parameters when calling the endpoint.
        cacheEnabled:
          type: boolean
          description: Controls whether to cache the response returned by your `GET` requests within a specified time-to-live (TTL) period.
        cacheTtl:
          type: integer
          format: int32
          description: The time-to-live (TTL) period in seconds for cached response when `cacheEnabled` is set to `true`.
          minimum: 30
          maximum: 600
      required:
      - timeout
      - rowLimit
      - paginationEnabled
      - cacheEnabled
      - cacheTtl
      description: The settings used in the endpoint.
    v1beta1EndpointParamsRes:
      type: object
      properties:
        name:
          type: string
          description: The user-defined name of the parameter.
        type:
          $ref: '#/components/schemas/v1beta1EndpointParamsType'
          description: "The user-defined data type of the parameter. \n - `string`\n - `number`\n - `integer`\n - `bool`\n - `array`"
        itemType:
          type: '#/definitions/v1beta1EndpointParamsItemType'
          description: "The item type of an array type parameter. \n - `string`\n - `number`\n - `integer`"
        required:
          type: boolean
          description: Specifies whether the parameter is required in the request.
        defaultValue:
          type: string
          description: The default value of the parameter. Make sure that the value matches the type of parameter you specified. Otherwise, the endpoint returns an error.
        description:
          type: string
          description: The description of the parameter.
        enum:
          type: string
          description: 'Specifies the value options of the parameter. To specify multiple values, you can separate them with a comma (`,`). For example: `"1,2"`.'
    v1beta1ListEndpointsResponse:
      type: object
      properties:
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/v1beta1EndpointRes'
          description: The items of endpoints in the Data App.
        nextPageToken:
          type: string
          description: The token to retrieve the next page of results.
      title: Response for ListEndpoint
    v1beta1Endpoint:
      type: object
      properties:
        displayName:
          type: string
          description: The name of the endpoint. By default, it is the same as the `path` value.
          minLength: 1
          maxLength: 32
          pattern: ^[a-zA-Z0-9_\-\/\[\]]+$
        description:
          type: string
          description: The user-defined description of the endpoint.
          minLength: 0
          maxLength: 2000
        path:
          type: string
          description: 'The user-defined HTTP path of the endpoint in the Data App. A path must start with a slash (`/`). For example: `"/v1/hello"`.'
          pattern: ^\/([a-zA-Z0-9_]+\/)*[a-zA-Z0-9_]+$
          minLength: 2
          maxLength: 64
        method:
          type: string
          description: 'The user-defined HTTP method of the endpoint. The supported HTTP methods are: `GET`, `POST`, `PUT`, and `DELETE`.'
        clusterId:
          type: string
          description: The ID of the TiDB cluster that is linked to the endpoint.
        params:
          type: array
          items:
            $ref: '#/components/schemas/v1beta1EndpointParams'
          description: The parameters used in the endpoint.
        settings:
          $ref: '#/components/schemas/v1beta1EndpointSettings'
          description: The settings used in the endpoint.
        tag:
          type: string
          description: The tag used for identifying a group of endpoints.
          default: Default
        batchOperation:
          type: boolean
          description: Controls whether to enable the endpoint to operate in batch mode. When it is set to `true`, you can operate on multiple rows in a single request.
        sqlTemplate:
          type: string
          description: Specifies the SQL statements to query data through the endpoint.
      required:
      - displayName
      - path
      - method
      - clusterId
      - settings
      - tag
      - sqlTemplate
    rpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/protobufAny'
    v1beta1EndpointArgs:
      type: object
      properties:
        items:
          type: object
          additionalProperties:
            type: string
          description: 'The key-value pairs used as parameters for endpoint testing, in the format of `key:value`. All values are of the string type. For example: `"limit":"2"`'
      required:
      - items
    protobufAny:
      type: object
      properties:
        '@type':
          type: string
      additionalProperties: {}
    v1beta1TestEndpointResponse:
      type: object
      properties:
        type:
          type: string
          description: Endpoint's type.
        data:
          $ref: '#/components/schemas/TestEndpointResponseData'
          description: The response of testing the endpoint.
      title: Response for TestEndpoint
    TestEndpointResponseResult:
      type: object
      properties:
        code:
          type: integer
          format: int32
          description: HTTPS status code of the request.
        message:
          type: string
          description: HTTPS result message of the request. If the status code returned by the request is 200, OK is returned here. If there is an error in the request, the specific reason for the error is returned.
        startMs:
          type: string
          format: int64
          description: 'The request''s start timestamp. For example: 1704871891280'
        endMs:
          type: string
          format: int64
          description: 'The request''s end timestamp. For example: 1704871891474'
        latency:
          type: string
          description: 'The request latency. For example: 194ms'
        rowCount:
          type: integer
          format: int32
          description: The number of rows that the request should return. Sometimes the maximum number of returned rows set by the user is exceeded. But in the end, only the number of rows returned is the minimum of these two values.
        rowAffect:
          type: integer
          format: int32
          description: When executing non-query SQL statements, the number of rows affected.
        limit:
          type: integer
          format: int32
          description: The maximum number of returned rows set by the request.
      description: 'Return basic information about request execution. For example: whether the execution is successful, execution time, number of items returned, etc.'
    TestEndpointResponseRow:
      type: object
      properties:
        items:
          type: object
          additionalProperties:
            type: string
          description: The columns and data results of the requested data table of the endpoint.
    v1beta1EndpointParamsType:
      type: string
      enum:
      - string
      - number
      - integer
      - bool
      - array
      description: "The user-defined data type of the parameter. \n - `string`\n - `number`\n - `integer`\n - `bool`\n - `array`"
    v1beta1EndpointSettingsRes:
      type: object
      properties:
        timeout:
          type: integer
          format: int32
          description: The user-defined timeout for the endpoint in milliseconds.
          minimum: 1
          maximum: 60000
        rowLimit:
          type: integer
          format: int32
          description: The maximum number of rows that the endpoint can operate or return.
          minimum: 1
          maximum: 2000
        paginationEnabled:
          type: boolean
          description: Controls whether to enable the pagination for the results returned by the `GET` request. When pagination is enabled, you can paginate the results by specifying `page` and `page_size` as query parameters when calling the endpoint.
        cacheEnabled:
          type: boolean
          description: Controls whether to cache the response returned by your `GET` requests within a specified time-to-live (TTL) period.
        cacheTtl:
          type: integer
          format: int32
          description: The time-to-live (TTL) period in seconds for cached response when `cacheEnabled` is set to `true`.
          minimum: 30
          maximum: 600
      description: The settings used in the endpoint.
    v1beta1EndpointRes:
      type: object
      properties:
        name:
          type: string
          description: The unique identifier for the endpoint, which is generated by the API and follows the format `dataApps/{dataAppId}/endpoints/{endpointId}`.
        status:
          type: string
          description: 'The deployment status of the endpoint:

            - `"deployed"`: the endpoint has been successfully deployed

            - `"draft"`: the endpoint is currently a draft and has not been deployed yet'
        displayName:
          type: string
          description: The name of the endpoint. By default, it is the same as the `path` value. You can update the name using [Update an endpoint for a Data App](#tag/Endpoint/operation/Endpoint_UpdateEndpoint).
        description:
          type: string
          description: The user-defined description of the endpoint.
        path:
          type: string
          description: 'The user-defined HTTP path of the endpoint in the Data App. A path must start with a slash (`/`). For example: `/v1/hello`.'
        method:
          type: string
          description: 'The user-defined HTTP method of the endpoint. The supported HTTP methods are: `GET`, `POST`, `PUT`, and `DELETE`.'
        clusterId:
          type: string
          description: The ID of the TiDB cluster that is linked to the endpoint.
        params:
          type: array
          items:
            $ref: '#/components/schemas/v1beta1EndpointParamsRes'
          description: The parameters used in the endpoint.
        settings:
          $ref: '#/components/schemas/v1beta1EndpointSettingsRes'
          description: The settings used in the endpoint.
        tag:
          type: string
          description: The tag used for identifying a group of endpoints.
          default: Default
        batchOperation:
          type: boolean
          description: Controls whether to enable the endpoint to operate in batch mode. When it is set to `true`, you can operate on multiple rows in a single request.
        sqlTemplate:
          type: string
          description: Specifies the SQL statements to query data through the endpoint.
        type:
          type: string
          description: The type of the endpoint, which cannot be set by the user.
          default: sql_endpoint
        returnType:
          type: string
          description: The response format of the endpoint. Currently, only JSON is supported, represented by the value "json". There is no need for user configuration.
        createdAt:
          type: string
          description: 'The timestamp when the endpoint was created. The time format follows the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard. For example: `"2023-06-03T06:52:08Z"`.'
        updatedAt:
          type: string
          description: 'The timestamp when the endpoint was last updated. The time format follows the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard. For example: `"2023-06-03T06:52:08Z"`.'
    v1beta1EndpointParams:
      type: object
      properties:
        name:
          type: string
          description: The user-defined name of the parameter.
        type:
          $ref: '#/components/schemas/v1beta1EndpointParamsType'
          description: "The user-defined data type of the parameter. \n - `string`\n - `number`\n - `integer`\n - `bool`\n - `array`"
        itemType:
          type: '#/definitions/v1beta1EndpointParamsItemType'
          description: "The item type of an array type parameter. \n - `string`\n - `number`\n - `integer`"
        required:
          type: boolean
          description: Specifies whether the parameter is required in the request.
        defaultValue:
          type: string
          description: The default value of the parameter. Make sure that the value matches the type of parameter you specified. Otherwise, the endpoint returns an error.
        description:
          type: string
          description: The description of the parameter.
        enum:
          type: string
          description: 'Specifies the value options of the parameter. To specify multiple values, you can separate them with a comma (`,`). For example: `"1,2"`.'
      required:
      - name
      - type
    TestEndpointResponseData:
      type: object
      properties:
        columns:
          type: array
          items:
            $ref: '#/components/schemas/TestEndpointResponseColumn'
          description: Returns the columns and columns' details of the requested data table of the endpoint.
        rows:
          type: array
          items:
            $ref: '#/components/schemas/TestEndpointResponseRow'
          description: Return the columns and data results of the requested data table of the endpoint.
        result:
          $ref: '#/components/schemas/TestEndpointResponseResult'
      title: Endpoint request data
x-tagGroups:
- name: Endpoints
  tags:
  - Data App
  - Data Source
  - Endpoint
  - Deployment
  - Data API Key
  - OpenAPI Specification