Documentation
Home Page API Gateway Cloud-native API Gateway Getting Started REST API lifecycle

REST API lifecycle

Updated at:
Copy as MD
Product

Cloud-native API Gateway provides full lifecycle management for REST APIs, covering design, development, testing, publishing, and unpublishing. REST APIs use standard HTTP methods, making them ideal for API-first development and fine-grained API control.

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

  1. Log on to the Cloud-native API Gateway console.

  2. In the navigation pane on the left, click API. In the top menu bar, select a region.

  3. Click Create API.

  4. 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.

    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.

  1. 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.

    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

  1. Log on to the Cloud-native API Gateway console.

  2. In the navigation pane on the left, click Instances. In the top menu bar, select a region.

  3. 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.

  4. 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.

    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 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).

    Note

    The 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.

    Important

    When 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

  1. On the details page of the REST API, click Add Operation.

  2. 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.

    Note

    These 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.

    Note

    This 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.

Publish an API

You can publish APIs from outside or within a gateway instance.

APIs outside an instance

  1. Log on to the Cloud-native API Gateway console. In the navigation pane on the left, click API, and select a region from the top menu bar.

  2. Click the target API, and in the upper-right corner, click Publish.

  3. In the Publish API panel, configure the parameters and click Publish.

    Configuration

    Description

    Domain Name

    Select the domain name for publishing. The API becomes accessible through this domain name.

    If no domain name is available, click Add Domain Name. Create a domain name.

    Instance

    Select the gateway instance. Use different instances for different environments.

    Scenario

    Scenarios include basic and canary. Backend service routing details are in Routing.

    Basic scenarios

    • Mock: Returns the mock response defined for the API. If no mock configuration exists, the API cannot be accessed.

      Note

      At least one operation must have mock configuration enabled, or publishing fails.

    • Single Service: All traffic is forwarded to a specific backend service. This is the most common scenario.

    Canary scenarios

    • By Percentage (Multi-service): Traffic is distributed to backend services by weight. Used for traffic shifting and canary releases.

      Note

      The sum of the weights for all services must equal 100.

    • By Content (Multi-service): Traffic is routed to backend services based on matching conditions. If you check Default for a rule, unmatched traffic goes to that rule's backend service.

      • Supported matching conditions: Equal, Prefix, and Regex Match.

      • Supported parameter types: Query and Header.

      Multiple matching conditions are combined with a logical AND.

      Important

      Only one rule can be set as Default. All other rules must have non-empty matching conditions.

    • By Tag (Proportion-based Routing): Traffic is distributed by weight to different versions of multiple backend services. For end-to-end canary releases, use single-service routing for better performance.

    Backend Services

    Associate a backend service under this gateway or VPC. If no backend service exists, click Create Service. Create a service.

    Publish Description

    Enter a description for the release.

APIs within an instance

  1. Log on to the Cloud-native API Gateway console. In the left navigation pane, choose Instance, and select a region from the top menu bar.

  2. On the Instance page, click the ID of the target gateway instance. In the navigation pane on the left, choose API, and then click the target API.

  3. In the upper-right corner, click Publish. This opens the Publish API panel, where you can configure the parameters and click Publish.

    Parameter

    Description

    Instance

    The gateway instance. Use different instances for different environments.

    VPC

    The VPC to which the instance's API operations belong.

    Publish Scope

    The release scope. Select an operation name to view affected operations.

    Publish Description

    Enter a description for the release.

Debug an API

  1. In the APIs, click the target API.

  2. On the Interface list tab, select the interface that you want to debug and click Debug.

  3. In the Debugging Operation pane, configure the parameters and click Send Request.

Access an API by domain name

  1. In the APIs, select the target API and click API Details.

  2. The API details page displays the publishing information.

    Two types of domain names are listed:

    • Environment second-level domain: A system-generated public domain name for testing only. Limited to 100 requests per day.

    • Domain name: A custom domain name configured during publishing. Create a CNAME record mapping it to the environment second-level domain. No daily request limit applies.

    Access path format: http(s)://{Domain Name}/{BasePath}/{API Path}.

Unpublish an API

Important

After unpublishing, the API stops processing requests on all associated domain names. Configuration and history are retained. Proceed with caution.

  1. You can unpublish an API from outside or within a gateway instance.

    API outside an instance

    1. 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.

    2. Click the target API, and in the upper-right corner, click More > Shutdown.

    API within an instance

    1. Log on to the Cloud-native API Gateway console. In the left navigation pane, choose Instance. In the top menu bar, select a region.

    2. On the Instance page, click the ID of the target gateway instance. In the navigation pane on the left, click API, and then click the target API.

    3. In the upper-right corner, click More > Shutdown.

  2. In the Confirm Unpublish dialog box, click Shutdown.

Previous：Use Cloud-native API Gateway to expose ACK microservicesNext：User Guide