This topic shows you how to create a REST API and add an operation.
Use cases
You can create APIs either within or outside an instance. Each method suits different use cases.
Create an API within an instance
Dedicated resource management: The API is used exclusively within a specific instance to manage specific resources or internal logic.
Security and isolation: Data or features require strict isolation and can be called only from within the instance.
Simplified service configuration: This method simplifies API management by confining configuration to a specific instance.
Create an API outside an instance
Cross-instance shared access: Allows multiple instances to 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 custom name for the API. The API 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
Enables or disables API version management. Different versions of an API are independent, sharing the same API name but allowing for different basic information and operations. To access a specific version, you must provide its version identifier in the request.
After you enable Version Management, you must configure Usage.
NoteIf 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 custom name for the API. The API 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 treated as independent APIs. They share the same API name but can have different basic information and operation details. To access a specific version, you must provide its version identifier in the request.
If you enable Version Management, you must configure the Usage parameter.
NoteIf 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 custom name for the API. The API 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
Enables or disables API version management. Different versions of an API are independent, sharing the same API name but allowing for different basic information and operations. To access a specific version, you must provide its version identifier in the request.
After you enable Version Management, you must configure Usage.
NoteIf 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 a use case for the current 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 backend service exists, click Create Service to create one.
ImportantWhen you create a new service, its port information may not be displayed immediately. Expand the Service Name drop-down list and click Refresh. Because this information is synchronized asynchronously, it might take a moment to appear.
Create a REST API by importing OpenAPI
You can import an OpenAPI file to create APIs either 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 custom name for the API. The API 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
Enables or disables API version management. Different versions of an API are independent, sharing the same API name but allowing for different basic information and operations. To access a specific version, you must provide its version identifier in the request.
After you enable Version Management, you must configure Usage.
NoteIf 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 custom name for the API. The API 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
Enables or disables API version management. Different versions of an API are independent, sharing the same API name but allowing for different basic information and operations. To access a specific version, you must provide its version identifier in the request.
After you enable Version Management, you must configure Usage.
NoteIf 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 a use case for the current 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 backend service exists, click Create Service to create one.
ImportantWhen you create a new service, its port information may not be displayed immediately. Expand the Service Name drop-down list and click Refresh. Because this information is synchronized asynchronously, it might 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 custom name for the operation. The name must be unique within the API.
Operation Path
The specific path of the operation.
Method
The request method of the operation. The combination of the 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 data structure for different response codes.
These definitions are for generating documentation 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
Enables or disables consumer authentication. This feature is disabled by default. If enabled, you must bind a consumer authorization to this operation for it to be accessible.