All Products
Search
Document Center

Publish API to API Gateway

Last Updated: Dec 29, 2020

Partners of Alibaba Cloud Marketplace who want to sell their API products in Alibaba Cloud Marketplace.

1. Overview

Intended readers:

After you are approved as a seller of the API marketplace, you can perform the following steps to publish your API product on Alibaba Cloud Marketplace:

  • Step 1: Configure and publish your API product in API Gateway.

  • Step 2: Go to the independent software vendor (ISV) portal of Alibaba Cloud Marketplace to configure the information about your API product,such as product description and sales information.

Goals:

  • This document introduces the information that API products contain and shows you how to perform the operations in Step 1, especially the operations that are related to API products.

  • This document describes how to configure API products in brief. For more information, see other documentation about API Gateway.

2. The Information that API Products Contain

When customers view API products on the website of Alibaba Cloud Marketplace, they will find the following three types of information:

a. Product introduction and sales information

1_上架

b. Other information about the API products, such as the product highlights, product description, pricing, reviews, and user guides.

2_产品详情

You must configure the API product information in a and b on the ISV portal of Alibaba Cloud Marketplace and configure the API operation information in API Gateway. An API product can contain multiple API operations. The API product in the preceding figures contains only one API operation.

3. Configure and Publish API Operation in API Gateway

3.1 Overview

Caution: To obtain the information about an API product on the ISV portal of Alibaba Cloud Marketplace, you must configure the API operations of the API product in API Gateway by using an approved ISV account.

3.2 Create an API Group

You must create an API group in API Gateway. An API group in API Gateway corresponds to an API product in Alibaba Cloud Marketplace. In the following figure, an API group is created in the Singapore region.

3_ap goup 14_API group2

Notice

Precautions:

Select a region. We recommend that you select the region that is closest to the region where the backend service of the API product resides. If the backend service of the API product is Function Compute or resides in a Virtual Private Cloud (VPC) of Alibaba Cloud, you must create the API group in the same region as the API product. To select the required API group when you create an API product on the ISV portal of Alibaba Cloud Market, you must select the region of the API group.

We recommend that you select Shared Instance (VPC Network) as the instance type for the API group.

You can customize the name and description for the API group, which are not displayed to users in the API product information.

5_Precaution

3.3 Configure API Operation

To publish the required API product, you must create the two API operations of the API product in the API group, as shown in the following figure.

6_Configure This section describes how to configure the API operation that is named "test1209_2".

3.3.1 Configure the Basic Information for the API Operation

Configure the basic information about the API operation, as shown in the following figure.

7_api operationPrecautions:

  • API Name: The name of the API operation will be displayed on the API product page, as shown in the following figure. You can also modify the name of the API operation after you publish the API product.

7
  • Security Certification: You must select Alibaba Cloud APP for this parameter.

  • AppCode Certification: You must select Open after puting on cloud market for this parameter. This way, when customers call the API operation, they can complete identify authentication in simple mode with an AppCode, or in encrypted mode with an AppKey and an AppSecret. For more information about the differences between the two authentication modes, see Call an API Operation by Using an AppCode.

  • API Options: You must select Allow cloud market for this parameter. Otherwise, the API operation cannot be displayed on the API product page.

3.3.2 Define the Request of the API Operation

Define the request of the API operation, as shown in the following figure.

8_request of api 19_request of api 2

Notice

Precautions:

  • Protocol: If the API operation is not a WebSocket API, select HTTPS.

  • Subdomain Name: API Gateway automatically allocates a second-level domain to the API operation. You do not need to change the second-level domain.

  • Request Path, HTTP Method, and Request Mode: You can set these parameters based on your API operation and its backend service. In this example, POST is selected for the HTTP Method parameter. Default values are used for the Request Path and Request Mode parameters.

  • Input Parameter Definition: In this example, three parameters indifferent locations are added. The Default Value, Example, and Description parameters are configured for three parameters.

3.3.3 Define the Backend Service of the API Operation

You must set the parameters in the following figure to configure how API Gateway communicates with the backend service of the API operation. The information about the backend service is not contained in the API product information. For more information, see the documentation of API Gateway.

10_api service

3.3.4 Define the Response of the API Operation

Define the response of the API operation, as shown in the following figure. We recommend that you set the Sample of Returned Results and Sample of Returned Failure parameters, and define error codes in the Error Code Definition section. Such information is displayed on the API product page to help customers better understand how to call the API operation. This can greatly reduce your workload in after-sales services.

11_response of api

3.3.5 Add Sample Code

We recommend that you provide sample code in addition to the preceding settings for the request and response of the API operation. This can improve the user experience and greatly reduce your workload in after-sales services. API Gateway automatically generates default sample code based on the configuration of the API operation, as shown in the following figure.

12_sample of api
Notice

Precautions:

  • The sample code applies to only API calls that use the AppCode-based authentication. The sample code that is automatically generated may have limits. For example, when customers call an API operation of an optical character recognition (OCR) product, they must encode images to Base64 and include the Base64 code in the request.

  • Such code cannot be automatically generated. We recommend that you edit the sample code on the Custom Sample Code page based on the features of the API product.

  • After you edit the sample code, API Gateway does not update the sample code even when API parameters are changed. You must update the sample code in time.

3.4 Publish and Debug the API Operation

After an API operation is configured, you must publish the API operation to an environment to test and call the API operation. In this example, the API operation is published to the production environment. For more information about how to manage environments in API Gateway, see Configure Different Environments for An API Operation.

13_Deploy apiThe authentication mode of the API operation is set to Alibaba Cloud APP. Therefore, you must create an application to debug the API operation after you publish the API operation. To create an application, you can click Create APP on the APPs page, as shown in the following figure.

14_application

Then, you must authorize the created application to use the API operation on the Authorization Information page. The following figure shows that authorization is completed.

15_Authorization

After that, you can debug the API operation on the Debug API page. Please follow the guide.

16_troubleshooting
Notice

Precautions:

  • In addition to the debugging on the API Debug page, we recommend that you run code to call the API operation for debugging. This way, you can make sure that the published API operation meets your requirements. If you set the authentication mode of the API operation to Alibaba Cloud APP, you can use the signature algorithm in an SDK or a custom signature algorithm. For more information, see Request Signature.

  • You can use the second-level domain that is automatically allocated to the API group to debug the API operation. However, this method may have limits. For more information, view the Details page.

3.5 Configure the Domain for the API Product

If you want to manage the published API operations in the API group throughout the full lifecycle in API Gateway, you must bind the complete domain to the API group. After that, the API operations can be called by business systems and client applications. However, if you want to publish the API product that corresponds to the API group to Alibaba Cloud Marketplace, you do not need to bind the complete domain to the API group. In this case, you only need to configure a third-level domain when you publish the API product on the ISV portal of Alibaba Cloud Marketplace, as shown in the following figure. After customers purchase the API product in Alibaba Cloud Marketplace, they can access the API product by using the domain of the API product.

17_domain
Notice

Precautions:

  • When you publish an API product on the ISV portal of Alibaba Cloud Marketplace, make sure that the prefix of the API endpoint is globally unique.

  • After you publish an API product, the domain of the API product is automatically bound to the API group that corresponds to the API product. Do not unbind or change the domain for the API group. Otherwise, customers may be unable to access the API product.

4. Publish API Product

For more information, see Publish API Products.