Help Center/ DataArts Studio/ API Reference/ DataArts DataService APIs/ API Management/ Create an API

Updated on 2025-11-17 GMT+08:00

View PDF

Create an API

Function

Create an API.

Calling Method

For details, see Calling APIs.

URI

POST /v1/{project_id}/service/apis

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details about how to obtain the project ID, see Project ID and Account ID.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token. This parameter is mandatory when token authentication is used. You can obtain it from the value of X-Subject-Token in the response message header returned by the "Obtaining a User Token" API of the IAM service.
workspace	Yes	String	Workspace ID. For details about how to obtain the workspace ID, see Instance ID and Workspace ID.
Dlm-Type	No	String	Specifies the version type of the data service. The value can be SHARED or EXCLUSIVE.
Content-Type	Yes	String	Type (format) of the message body. This parameter is mandatory if the message body exists. If the message body does not exist, leave this parameter blank. If the request body contains Chinese characters, use charset=utf8 to specify the Chinese character set, for example, application/json;charset=utf8.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
catalog_id	No	String	Catalog ID.
name	No	String	API name
description	No	String	API description
log_flag	No	Boolean	Indicates whether to enable the access log function.
api_type	No	String	API type Enumerated values: API_SPECIFIC_TYPE_CONFIGURATION: configuration API API_SPECIFIC_TYPE_SCRIPT: script API API_SPECIFIC_TYPE_MYBATIS: MyBatis API API_SPECIFIC_TYPE_GROOVY: Groovy API API_SPECIFIC_TYPE_REGISTER: registered API API_SPECIFIC_TYPE_ORCHESTRATE: orchestrated API API_TYPE_CREATE: created API (obsolete) API_TYPE_REGISTER: registered API (obsolete)
auth_type	No	String	Authentication mode Enumerated values: APP: app secret IAM: IAM token NONE: authentication disabled
retention_period	No	Integer	Minimum retention period in hours
manager	No	String	API reviewer
path	No	String	API path
protocol	No	String	API request protocol type. Enumerated values: PROTOCOL_TYPE_HTTP: HTTP PROTOCOL_TYPE_HTTPS: HTTPS
request_type	No	String	Request type Enumerated values: REQUEST_TYPE_POST: POST REQUEST_TYPE_GET: GET
tags	No	Array of strings	Tag
visibility	No	String	API visibility Enumerated values: WORKSPACE: visible to a workspace PROJECT: visible to a project DOMAIN: visible to a tenant
publish_type	No	String	Publishing type (obsolete) Enumerated values: PUBLISH_TYPE_PUBLIC: public PUBLISH_TYPE_PRIVATE: private
data_mask_switch	No	Boolean	Whether to enable data masking
data_mask_paras	No	Array of DataMaskParas objects	Data masking poarameters
body	No	String	Request body description. It is available for registration APIs only.
datasource_config_list	No	Array of DatasourceConfig objects	Configuration of multiple data sources. It is available for Groovy APIs only.
groovy_content	No	String	Groovy text. It is available for Groovy APIs only.
request_paras	No	Array of RequestPara objects	List of API request parameters.
datasource_config	No	DatasourceConfig object	API data source configuration.
backend_config	No	BackendConfig object	API backend configuration. It is available for registration APIs only.

**Table 4** DataMaskParas
Parameter	Mandatory	Type	Description
column_name	No	String	Sensitive field
algorithm_name	No	String	Algorithm name
algorithm_type	No	String	Algorithm type
en_name	No	String	Algorithm name
algorithm_parameters	No	String	Parameter
failure_policy	No	String	Failure policy Enumerated values: SKIP INTERRUPT_AND_EXCEPTION SET_NULL DEFAULT_VALUE

**Table 5** DatasourceConfig
Parameter	Mandatory	Type	Description
type	No	String	Data source type. Enumerated values: MYSQL DLI DWS HIVE HBASE
connection_name	No	String	Name of a data connection.
connection_id	No	String	Data connection ID.
database	No	String	Indicates the database name.
datatable	No	String	Name of a data table.
table_id	No	String	Data table ID.
queue	No	String	Queue name of DLI.
access_mode	No	String	Mode for obtaining data Enumerated values: SQL: SQL ROW_KEY: ROW_KEY, available only for HBase PREFIX_FILTER: PREFIX_FILTER, available only for HBase
access_type	No	String	Mode for obtaining data (obsolete) Enumerated values: SCRIPT: script CONFIGURAITON: configuration
pagination	No	String	Pagination mode Enumerated values: DEFAULT: default CUSTOM: custom
sql	No	String	SQL statement in script mode
backend_paras	No	Array of ApiRequestPara objects	API backend parameter.
response_paras	No	Array of ApiResponsePara objects	Return parameters of configuration APIs.
order_paras	No	Array of DatasourceOrderPara objects	Sorting parameter.
total_size_sql	No	String	SQL script for calculating the total number of records

**Table 6** RequestPara
Parameter	Mandatory	Type	Description
name	No	String	Parameter name
position	No	String	Parameter position Enumerated values: REQUEST_PARAMETER_POSITION_PATH: request path REQUEST_PARAMETER_POSITION_HEADER: request header REQUEST_PARAMETER_POSITION_QUERY: request query
type	No	String	Constant parameter type Enumerated values: REQUEST_PARAMETER_TYPE_NUMBER: number REQUEST_PARAMETER_TYPE_STRING: string
description	No	String	Parameter description.
necessary	No	Boolean	Indicates whether a parameter is mandatory.
example_value	No	String	Example value
default_value	No	String	Default value.
support_null	No	Boolean	Null supported

**Table 7** ApiRequestPara
Parameter	Mandatory	Type	Description
name	No	String	Parameter name
mapping	No	String	Mapping field.
condition	No	String	Operator Enumerated values: CONDITION_TYPE_EQ: equal to CONDITION_TYPE_NE: not equal to CONDITION_TYPE_GT: greater than CONDITION_TYPE_GE: greater than or equal to CONDITION_TYPE_LT: less than CONDITION_TYPE_LE: less than or equal to CONDITION_TYPE_LIKE: fuzzy search, such as %like% CONDITION_TYPE_LIKE_L: fuzzy search, such as %like CONDITION_TYPE_LIKE_R: fuzzy search, such as like%

**Table 8** ApiResponsePara
Parameter	Mandatory	Type	Description
name	No	String	Parameter name
field	No	String	Bound table field.
type	No	String	Constant parameter type Enumerated values: REQUEST_PARAMETER_TYPE_NUMBER: number REQUEST_PARAMETER_TYPE_STRING: string
description	No	String	Parameter description.
example_value	No	String	Example value of a parameter.

**Table 9** DatasourceOrderPara
Parameter	Mandatory	Type	Description
name	No	String	Name of a sorting parameter.
field	No	String	Indicates the corresponding parameter field.
optional	No	Boolean	Indicates whether the parameter is optional.
sort	No	String	Sorting method Enumerated values: ASC: ascending order DESC: descending order CUSTOM: custom order
order	No	Integer	Sequence of sorting parameters.
description	No	String	Sorting parameter description

**Table 10** BackendConfig
Parameter	Mandatory	Type	Description
type	No	String	Request type REQUEST_TYPE_POST: POST request REQUEST_TYPE_GET: GET request
protocol	No	String	API request protocol type PROTOCOL_TYPE_HTTP: HTTP PROTOCOL_TYPE_HTTPS: HTTPS
host	No	String	Backend host
timeout	No	Integer	Backend timeout interval.
path	No	String	Backend request path
backend_paras	No	Array of BackendRequestPara objects	API backend parameter.
constant_paras	No	Array of BackendConstant objects	Backend constant parameter.

**Table 11** BackendRequestPara
Parameter	Mandatory	Type	Description
name	No	String	API request parameter name
position	No	String	Parameter position Enumerated values: REQUEST_PARAMETER_POSITION_PATH: request path REQUEST_PARAMETER_POSITION_HEADER: request header REQUEST_PARAMETER_POSITION_QUERY: request query
backend_para_name	No	String	Backend parameter.

**Table 12** BackendConstant
Parameter	Mandatory	Type	Description
name	No	String	Name of a constant parameter.
type	No	String	Constant parameter type Enumerated values: REQUEST_PARAMETER_TYPE_NUMBER: number REQUEST_PARAMETER_TYPE_STRING: string
position	No	String	Parameter position Enumerated values: REQUEST_PARAMETER_POSITION_PATH: request path REQUEST_PARAMETER_POSITION_HEADER: request header REQUEST_PARAMETER_POSITION_QUERY: request query
description	No	String	Constant parameter description.
value	No	String	Constant parameter value.

Response Parameters

Status code: 200

**Table 13** Response body parameters
Parameter	Type	Description
id	String	ID of the API that is successfully created.

Status code: 400

**Table 14** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Example Requests

Create a configuration API.

/v1/0833a5737480d53b2f250010d01a7b88/service/apis

{
  "catalog_id" : "0",
  "name" : "create_config_api",
  "description" : "dws",
  "visibility" : "WORKSPACE",
  "api_type" : "API_SPECIFIC_TYPE_CONFIGURATION",
  "auth_type" : "APP",
  "retention_period" : "1",
  "manager" : "user",
  "log_flag" : true,
  "path" : "/pathrGW6riuO/{p}",
  "protocol" : "PROTOCOL_TYPE_HTTPS",
  "request_type" : "REQUEST_TYPE_POST",
  "request_paras" : [ {
    "name" : "a",
    "position" : "REQUEST_PARAMETER_POSITION_QUERY",
    "type" : "REQUEST_PARAMETER_TYPE_STRING",
    "description" : "1",
    "necessary" : true,
    "example_value" : "1",
    "default_value" : "1",
    "support_null" : false
  }, {
    "name" : "b",
    "position" : "REQUEST_PARAMETER_POSITION_HEADER",
    "type" : "REQUEST_PARAMETER_TYPE_STRING",
    "description" : "1",
    "necessary" : true,
    "example_value" : "1",
    "default_value" : "1",
    "support_null" : false
  }, {
    "name" : "c",
    "position" : "REQUEST_PARAMETER_POSITION_BODY",
    "type" : "REQUEST_PARAMETER_TYPE_STRING",
    "description" : "1",
    "necessary" : true,
    "example_value" : "1",
    "default_value" : "1",
    "support_null" : false
  }, {
    "name" : "p",
    "position" : "REQUEST_PARAMETER_POSITION_PATH",
    "type" : "REQUEST_PARAMETER_TYPE_STRING",
    "description" : "ok1",
    "necessary" : true,
    "example_value" : "ok1",
    "default_value" : "ok1",
    "support_null" : false
  } ],
  "datasource_config" : {
    "access_mode" : "SQL",
    "order_paras" : [ ],
    "table_id" : "NativeTable-c68d84bd2d89420cb2458b4e06805ddf-postgres-dbadmin-test3",
    "datatable" : "dbadmin.test3",
    "database" : "postgres",
    "connection_id" : "c68d84bd2d89420cb2458b4e06805ddf",
    "connection_name" : "yqp_dws",
    "type" : "DWS",
    "pagination" : "DEFAULT",
    "sql" : "",
    "total_size_sql" : "",
    "backend_paras" : [ {
      "name" : "a",
      "mapping" : "username",
      "condition" : "CONDITION_TYPE_EQ"
    } ],
    "response_paras" : [ {
      "description" : "",
      "example_value" : "",
      "field" : "id_num",
      "name" : "id_num",
      "type" : "REQUEST_PARAMETER_TYPE_STRING"
    }, {
      "description" : "",
      "example_value" : "",
      "field" : "username",
      "name" : "username",
      "type" : "REQUEST_PARAMETER_TYPE_STRING"
    } ]
  },
  "data_mask_switch" : false,
  "data_mask_paras" : [ ]
}

Create a script API.

/v1/0833a5737480d53b2f250010d01a7b88/service/apis

{
  "catalog_id" : "0",
  "name" : "create_script_api",
  "description" : "dws",
  "visibility" : "WORKSPACE",
  "api_type" : "API_SPECIFIC_TYPE_SCRIPT",
  "auth_type" : "APP",
  "retention_period" : "1",
  "manager" : "user",
  "log_flag" : true,
  "path" : "/pathR7YL3xfN/{p}",
  "protocol" : "PROTOCOL_TYPE_HTTPS",
  "request_type" : "REQUEST_TYPE_POST",
  "request_paras" : [ {
    "name" : "a",
    "position" : "REQUEST_PARAMETER_POSITION_QUERY",
    "type" : "REQUEST_PARAMETER_TYPE_STRING",
    "description" : "1",
    "necessary" : true,
    "example_value" : "1",
    "default_value" : "1",
    "support_null" : false
  }, {
    "name" : "b",
    "position" : "REQUEST_PARAMETER_POSITION_HEADER",
    "type" : "REQUEST_PARAMETER_TYPE_STRING",
    "description" : "1",
    "necessary" : true,
    "example_value" : "1",
    "default_value" : "1",
    "support_null" : false
  }, {
    "name" : "c",
    "position" : "REQUEST_PARAMETER_POSITION_BODY",
    "type" : "REQUEST_PARAMETER_TYPE_STRING",
    "description" : "1",
    "necessary" : true,
    "example_value" : "1",
    "default_value" : "1",
    "support_null" : false
  }, {
    "name" : "p",
    "position" : "REQUEST_PARAMETER_POSITION_PATH",
    "type" : "REQUEST_PARAMETER_TYPE_STRING",
    "description" : "ok1",
    "necessary" : true,
    "example_value" : "ok1",
    "default_value" : "ok1",
    "support_null" : false
  } ],
  "datasource_config" : {
    "access_mode" : "SQL",
    "order_paras" : [ ],
    "database" : "dls",
    "connection_id" : "c68d84bd2d89420cb2458b4e06805ddf",
    "connection_name" : "yqp_dws",
    "type" : "DWS",
    "pagination" : "CUSTOM",
    "sql" : "c2VsZWN0IDMsNCw1",
    "total_size_sql" : "",
    "backend_paras" : [ {
      "name" : "a",
      "mapping" : "a",
      "condition" : "CONDITION_TYPE_EQ"
    }, {
      "name" : "b",
      "mapping" : "b",
      "condition" : "CONDITION_TYPE_EQ"
    }, {
      "name" : "c",
      "mapping" : "c",
      "condition" : "CONDITION_TYPE_EQ"
    }, {
      "name" : "p",
      "mapping" : "p",
      "condition" : "CONDITION_TYPE_EQ"
    } ]
  },
  "data_mask_switch" : false,
  "data_mask_paras" : [ ]
}

Create a MyBatis API.

/v1/0833a5737480d53b2f250010d01a7b88/service/apis

{
  "catalog_id" : "0",
  "name" : "create_mybatis_api",
  "description" : "desc",
  "visibility" : "WORKSPACE",
  "api_type" : "API_SPECIFIC_TYPE_MYBATIS",
  "auth_type" : "APP",
  "retention_period" : "0",
  "manager" : "user",
  "log_flag" : true,
  "path" : "/pathR7YL3xfN",
  "protocol" : "PROTOCOL_TYPE_HTTPS",
  "request_type" : "REQUEST_TYPE_POST",
  "request_paras" : [ {
    "name" : "ssss",
    "position" : "REQUEST_PARAMETER_POSITION_QUERY",
    "type" : "REQUEST_PARAMETER_TYPE_STRING",
    "description" : "1",
    "necessary" : true,
    "example_value" : "1",
    "default_value" : "1",
    "support_null" : false
  } ],
  "datasource_config" : {
    "access_mode" : "SQL",
    "order_paras" : [ ],
    "database" : "dls",
    "connection_id" : "c68d84bd2d89420cb2458b4e06805ddf",
    "connection_name" : "yqp_dws",
    "type" : "DWS",
    "pagination" : "CUSTOM",
    "sql" : "c2VsZWN0IDEKPGlmIHRlc3Q9InNzc3MgPT0gJzEnLnRvU3RyaW5nKCkiPiAgCiwyIAo8L2lmPg==",
    "total_size_sql" : "",
    "backend_paras" : [ ]
  },
  "data_mask_switch" : false,
  "data_mask_paras" : [ ]
}

Example Responses

Status code: 200

Success

{
  "id" : "6b9e682fd6d0ef7c0f67470124b20762"
}

Status Codes

Status Code	Description
200	Success
400	Bad request

Parent Topic: API Management

Previous topic: API Management

Next topic: Querying an API List

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel