API property descriptions

Property

Required

Description

API name

Yes

• Identifies the API.

• The value must be no longer than 32 characters, start with a Chinese character or an English letter, and contain only Chinese characters, English letters, digits, underscores (_), and hyphens (-).

• API names must be unique within the same workspace.

Create from an existing API

No

• Disabled by default.

• If enabled, you can select an existing API as a template.

API group

Yes

• Logically groups APIs. APIs in a group are isolated by the same group ID.

• API group names must be unique within the same environment.

• The API group name can contain English letters, numbers, underscores (_), and hyphens (-). It must be 32 characters or less.

API description

No

A description of the API's purpose. Up to 64 characters.

Application

Yes

• Application: After the API is published, it can be called by web browsers, H5 containers, miniapps, JS, and business systems.

• mPaaS mobile application: After the API is published, it can be called by mPaaS mobile clients (iOS and Android).

• Application and mPaaS mobile application: After the API is published, it can be called by web browsers, H5 containers, miniapps, JS, and business systems, along with mPaaS mobile clients (iOS and Android).

OperationType

Yes

• An API service identifier for mPaaS mobile applications. It locates the resource to access.

• The identifier can contain English letters, numbers, and periods (.). It must be 200 characters or less.

• Enter the identifier in the format com.xxx.opt1.

Request path

Yes

• The URL of the requested resource. The request path locates the resource.

• The path can contain English letters, numbers, underscores (_), and hyphens (-). It must be 200 characters or less.

• The path must start with a forward slash (/) but not end with one. For example, /getUserInfo.

• The path supports the placeholder pattern /home/{id}. If the placeholder must be passed through to the control plane, leave the backend request path of the API empty.

Method

Yes

The action to perform on the HTTP resource:

• GET: Retrieves data from the server.

• POST: Sends data to the server for processing.

• PUT: Updates data stored on the server.

• DELETE: Deletes data from the server.

Path matching rule

Yes

• Exact match: The call must exactly match the path you entered. For example, /path.

• Prefix match: Matches multiple paths that start with the specified request path. For example, entering /path has the same effect as /path/*.

Security authentication

Yes

• Select an authentication method as needed. Supported methods include key authentication, no authentication, OAuth authentication, Key-Auth authentication, Basic-Auth authentication, and JWT authentication.

Interface name

Yes

• The name of the interface that the client RPC service or Dubbo service subscribes to.

• The API interface name can contain lowercase letters, numbers, periods (.), colons (:), and at signs (@). It must start with a lowercase letter.

• For example, com.alipay.testapp.facade.ConfigFacade:1.0@DEFAULT.

Service identity

No

Optional. Specify a service by its uniqueId.

Method name

Yes

• The name of the method in the interface that the client RPC service or Dubbo service subscribes to.

• The API service method name can contain English letters and numbers. It must start with a letter.

• For example, getUserID.

Message type

Yes

The media type of the request and response. This tells the server how to process request data. It also tells the client, typically a browser, how to parse response data.

Message encoding

Yes

The character set that the client accepts for text content.

Entity parameter

No

The full path of the entity parameter used by the client Dubbo service interface method. For example, `Ljava/lang/String;`. Custom parameter entities must end with a semicolon (;).

Return parameter

No

The full path of the return parameter from the client Dubbo service interface method. For example, `Ljava/lang/String;`. Custom parameter entities must end with a semicolon (;).

Dubbo group

No

The service group for the client Dubbo service interface subscription.

Property

Required

Description

Parameter name

No

A unique identifier for the parameter.

Parameter location

No

• Header: A custom API request header. For example, X-MyHeader: Value.

• Query: The parameter appears after the question mark (?) at the end of the request URL in the format name=value. Parameters are separated by ampersands (&). For example, /users?role=admin&id=12345.

Type

No

• String

• Int

• Long

• Double

• Float

• Boolean

Default value

No

The default value used when the parameter value in the API request is empty. The default value type must match the parameter type.

Description

No

A business description of the parameter.

Request Body Type

No

The type of the request body. These are parameters configured for requests that the client sends to the gateway. You can use existing data models.

When you use the orchestration feature, an API must have a data model selected to transform and pass through parameters. To generate a software development kit (SDK) in an API group, you must select a data model for the request body or response body.

• Long

• Int

• Float

• Double

• Boolean

• Byte

• Short

• String

• List: Select a basic type or a data model as the parameter template.

• Object: Select a data model as the parameter template.

• Map: Select a basic type or a data model as the parameter template.

Property

Required

Description

Successful response example

No

A sample of the data returned on a successful request. This serves as a reference for API subscribers.

Failed response example

No

A sample of the data returned on a failed request. This serves as a reference for API subscribers.

Error code

No

Default HTTP error codes.

Error message

No

A custom error message.

Description

No

A business description of the error code.

Response body type

No

The parameters of the response. You can use existing data models.

When you use the orchestration feature, an API must have a data model selected to transform and pass through parameters. To generate an SDK in an API group, you must select a data model for the request body or response body.

• Long

• Int

• Float

• Double

• Boolean

• Byte

• Short

• String

• List: Select a basic type or a data model as the parameter template.

• Object: Select a data model as the parameter template.

• Map: Select a basic type or a data model as the parameter template.

Property

Required

Description

Backend service type

Yes

The type of backend service to which the gateway forwards requests:

• Mock: Simulates a backend service if the actual service is not yet available.

• System cluster: Forwards the request to the cluster of the actual business system.

Protocol Type

Yes

The communication protocol used by the backend service that accepts the forwarded request. Supported protocols:

• HTTP

• SOFARPC

• SOFAREST

• DUBBO

• DUBBOX

Request path

No

The actual request path on the server. If you leave this empty, the request path from the API definition is used by default.

Path stripping level

No

Only numbers are supported.

Append path prefix

No

The path prefix to add to the backend request. The prefix must start with a forward slash (/) but not end with one.

Timeout

Yes

The API request timeout period in milliseconds (ms). The default value is 3000 ms.

Routing policy

Yes

The policy used by the gateway to route requests:

• Route by Header: Routes requests based on parameters in the request header.

• Route by LDC: Uses LDC unit-based routing.

• Route by weight: The value range is 0 to 100. The sum of all rules must be 100.

• Route by request path: Forwards the request directly.

Interface name

Yes

• The name of the interface published by the server-side RPC, SOFAREST, or Dubbo service.

• The API interface name can contain lowercase letters, numbers, periods (.), colons (:), and at signs (@). It must start with a lowercase letter.

• For example, com.alipay.testapp.facade.ConfigFacade:1.0@DEFAULT.

Method name

Yes

• The name of the method in the interface that the RPC or Dubbo service subscribes to.

• The API service method name can contain English letters and numbers. It must start with a letter.

• For example, getUserID.

Entity parameter

No

The full path of the entity parameter used by the server-side Dubbo service interface method. For example, `Ljava/lang/String;`. Custom parameter entities must end with a semicolon (;).

Return parameter

No

The full path of the return parameter from the server-side Dubbo service interface method. For example, `Ljava/lang/String;`. Custom parameter entities must end with a semicolon (;).

Dubbo group

No

The service group for the server-side Dubbo service interface subscription.

System cluster

Yes

Select the system cluster to attach to the backend.

Parameter mapping configuration

No

Configure mappings between request and response parameters. You can select an existing parameter mapping rule.