Cloud-native API Gateway supports creating REST APIs within or outside an instance, either from the console or by importing an OpenAPI file. After creating an API, you can add operations to define request paths and methods.
Use cases
APIs can be created within or outside an instance, depending on your use case.
Create an API within an instance
-
Dedicated resource management: The API manages resources or internal logic within a specific instance only.
-
Security and isolation: Data or features require strict isolation and are callable only from within the instance.
-
Simplified service configuration: Confining configuration to a specific instance simplifies API management.
Create an API outside an instance
-
Cross-instance shared access: Multiple instances share a single API definition.
-
Centralized management and monitoring: Unified permission control, logging, and traffic management.
Create a REST API in the console
Cloud-native API Gateway provides two ways to create APIs in the console: within an instance and outside an instance.
Outside an instance
-
Log on to the Cloud-native API Gateway console.
-
In the navigation pane on the left, click API. In the top menu bar, select a region.
-
Click Create API.
-
On the REST API card, click Create. In the Create REST API panel, configure the parameters and click Confirm.
Parameter
Description
API Name
Enter a name for the API. The name must be globally unique.
Base path
The base path for the API. When a client calls a specific operation, the full request URL is
http(s)://{domain name}/{base path}/{operation path}.Version Management
Specifies whether to enable API version management. Different versions of an API are independent. They share the same API name but can have different basic information and operations. To access a specific version, include its version identifier in the request.
If you enable Version Management, you must also configure Usage.
Note-
If you set Usage to Query, you must configure the Add Query parameter.
-
If you set Usage to Header, you must configure the Add Header parameter.
Usage
The version identifier can be passed in the Path, a Query parameter, or a Header.
-
Path: The full request path is
/{base path}/{version_number}/{operation_path}. -
Query: The full request path is
/{base path}/{operation_path}. The request must include the query parameter that you specified in Add Query, with its value set to the version number. -
Header: The full request path is
/{base path}/{operation_path}. The request must include the header that you specified in Add Header, with its value set to the version number.
Description
Enter a description for the API.
Resource Group
Select the target resource group. To create a new one, click Create Resource Group on the right.
-
Click Create API.
-
On the REST API card, click Create. In the Create REST API panel, configure the parameters and click Confirm.
Parameter
Description
API Name
Enter a name for the API. The name must be globally unique.
Base path
The base path for the API. When a client calls a specific operation, the full request URL is
http(s)://{domain name}/{base path}/{operation path}.Version Management
Specifies whether to enable API version management. Different versions of an API are independent. They share the same API name but can have different basic information and operations. To access a specific version, include its version identifier in the request.
If you enable Version Management, you must also configure the Usage parameter.
Note-
If you set Usage to Query, you must configure the Add Query parameter.
-
If you set Usage to Header, you must configure the Add Header parameter.
Usage
The version identifier can be passed in the Path, a Query parameter, or a Header.
-
Path: The full request path is
/{base path}/{version_number}/{operation_path}. -
Query: The full request path is
/{base path}/{operation_path}. The request must include the query parameter that you specified in Add Query, with its value set to the version number. -
Header: The full request path is
/{base path}/{operation_path}. The request must include the header that you specified in Add Header, with its value set to the version number.
Description
Enter a description for the API.
Resource Group
Select the target resource group. To create a new one, click Create Resource Group on the right.
-
Within an instance
-
Log on to the Cloud-native API Gateway console.
-
In the navigation pane on the left, click Instances. In the top menu bar, select a region.
-
On the Instances page, click the target Instance ID to go to the Overview page. In the navigation pane on the left, click API, and then click Create API.
-
On the REST API card, click Create. In the Create REST API panel, configure the parameters and click Confirm.
Parameter
Description
API Name
Enter a name for the API. The name must be globally unique.
Domain Name
-
Select one or more domain names for the API.
-
To create a new domain name, click Add Domain Name.
Base path
The base path for the API. When a client calls a specific operation, the full request URL is
http(s)://{domain name}/{base path}/{operation path}.Version Management
Specifies whether to enable API version management. Different versions of an API are independent. They share the same API name but can have different basic information and operations. To access a specific version, include its version identifier in the request.
If you enable Version Management, you must also configure Usage.
Note-
If you set Usage to Query, you must configure the Add Query parameter.
-
If you set Usage to Header, you must configure the Add Header parameter.
Usage
The version identifier can be passed in the Path, a Query parameter, or a Header.
-
Path: The full request path is
/{base path}/{version_number}/{operation_path}. -
Query: The full request path is
/{base path}/{operation_path}. The request must include the query parameter that you specified in Add Query, with its value set to the version number. -
Header: The full request path is
/{base path}/{operation_path}. The request must include the header that you specified in Add Header, with its value set to the version number.
Description
Enter a description for the API.
Resource Group
Select the target resource group. To create a new one, click Create Resource Group on the right.
Scenario
Select the use case for this operation.
-
Basic scenario: Single Service.
-
Canary release scenarios: By Percentage (Multi-service), By Content (Multi-service), and By Tag (Proportion-based Routing).
NoteThe sum of traffic percentages for all target services must be 100%.
Backend Services
Associate a backend service from the current gateway or VPC. If no service exists, click Create Service to create one.
ImportantWhen you create a new service, its port information may not appear immediately. Expand the Service Name drop-down list and click Refresh. The information is synchronized asynchronously and may take a moment to appear.
-
Create a REST API by importing OpenAPI
You can import an OpenAPI file to create APIs within or outside an instance.
Outside an instance
-
Log on to the Cloud-native API Gateway console.
-
In the navigation pane on the left, click API. In the top menu bar, select a region.
-
Click Create API.
-
On the REST API card, click Import. In the Create File based on OpenAPI panel, configure the parameters and click Precheck and Create.
Parameter
Description
API Name
Enter a name for the API. The name must be globally unique.
Upload method
You can use a Local File or Import OSS files.
NoteFiles for both local upload and OSS import must comply with the OpenAPI specification.
OpenAPI File
Select a local file or paste its text content. The file size cannot exceed 30 MB.
Region selection
Select the region where your OSS resources are located.
OSS bucket
Select an OSS bucket. Buckets that do not have a region attribute are not supported.
Version Management
Specifies whether to enable API version management. Different versions of an API are independent. They share the same API name but can have different basic information and operations. To access a specific version, include its version identifier in the request.
If you enable Version Management, you must also configure Usage.
Note-
If you set Usage to Query, you must configure the Add Query parameter.
-
If you set Usage to Header, you must configure the Add Header parameter.
Usage
The version identifier can be passed in the Path, a Query parameter, or a Header.
-
Path: The full request path is
/{base path}/{version_number}/{operation_path}. -
Query: The full request path is
/{base path}/{operation_path}. The request must include the query parameter that you specified in Add Query, with its value set to the version number. -
Header: The full request path is
/{base path}/{operation_path}. The request must include the header that you specified in Add Header, with its value set to the version number.
Description
Enter a description for the API.
Resource Group
Select the target resource group. To create a new one, click Create Resource Group on the right.
-
Within an instance
-
Log on to the Cloud-native API Gateway console.
-
In the navigation pane on the left, click Instances. In the top menu bar, select a region.
-
On the Instances page, click the target Instance ID to go to the Overview page. In the navigation pane on the left, click API, and then click Create API.
-
On the REST API card, click Import. In the Create File based on OpenAPI panel, configure the parameters and click Precheck and Create.
Parameter
Description
API Name
Enter a name for the API. The name must be globally unique.
Domain Name
-
Select one or more domain names for the API.
-
To create a new domain name, click Add Domain Name.
Upload method
You can use a Local File or Import OSS files.
NoteFiles for both local upload and OSS import must comply with the OpenAPI specification.
OpenAPI File
Select a local file or paste its text content. The file size cannot exceed 30 MB.
Region selection
Select the region where your OSS resources are located.
OSS bucket
Select an OSS bucket. Buckets that do not have a region attribute are not supported.
Version Management
Specifies whether to enable API version management. Different versions of an API are independent. They share the same API name but can have different basic information and operations. To access a specific version, include its version identifier in the request.
If you enable Version Management, you must also configure Usage.
Note-
If you set Usage to Query, you must configure the Add Query parameter.
-
If you set Usage to Header, you must configure the Add Header parameter.
Usage
The version identifier can be passed in the Path, a Query parameter, or a Header.
-
Path: The full request path is
/{base path}/{version_number}/{operation_path}. -
Query: The full request path is
/{base path}/{operation_path}. The request must include the query parameter that you specified in Add Query, with its value set to the version number. -
Header: The full request path is
/{base path}/{operation_path}. The request must include the header that you specified in Add Header, with its value set to the version number.
Description
Enter a description for the API.
Resource Group
Select the target resource group. To create a new one, click Create Resource Group on the right.
Scenario
Select the use case for this operation.
-
Basic scenario: Single Service.
-
Canary release scenarios: By Percentage (Multi-service), By Content (Multi-service), and By Tag (Proportion-based Routing).
NoteThe sum of traffic percentages for all target services must be 100%.
Backend Services
Associate a backend service from the current gateway or VPC. If no service exists, click Create Service to create one.
ImportantWhen you create a new service, its port information may not appear immediately. Expand the Service Name drop-down list and click Refresh. The information is synchronized asynchronously and may take a moment to appear.
-
Add an operation
-
On the details page of the REST API, click Add Operation.
-
In the Add Operation panel, configure the parameters and click Add.
Parameter
Description
Operation Name
Enter a name for the operation. The name must be unique within the API.
Operation Path
The request path for this operation.
Method
The HTTP method for this operation. The combination of operation path and method must be unique within the API.
Description
Enter a description for the operation.
Request Definition
You can define Header, Query, and path parameters, as well as a Body.
Path parameters can be defined in the operation path in one of the following three formats:
-
/books/{bookId}
-
/books/[bookId]
-
/books/:bookId
We recommend that you use the
{bookId}format.NoteThese definitions are for generating SDKs and documentation only and are not validated at runtime.
Response Definition
Defines the response data structure for different status codes.
These definitions are used for documentation generation only and are not validated at runtime.
Mock
Mock configurations take effect only when the API is published to a mock environment.
NoteThis feature is only available for APIs created outside an instance.
Consumer Authentication
Specifies whether to enable consumer authentication. Disabled by default. If enabled, you must bind a consumer authorization to this operation for it to be accessible.
-