All Products
Search
Document Center

Create an API with OSS as the backend service

Last Updated: Mar 11, 2022

This topic describes how to create and publish an API with Object Storage Service (OSS) as the backend service in API Gateway, and how to call the API by using an AppKey and AppSecret pair of an APP. The AppKey and AppSecret are automatically generated for the APP if you set the authentication method of the API to Alibaba Cloud APP.

1. Overview

You must perform the following steps in sequence:

  • Activate OSS

  • Create an API group

  • Create and define an API

  • Create an APP and grant the APP the permissions to call the API

  • Debug the API

  • Call the API

2. Create an OSS bucket

OSS is a secure and cost-effective Alibaba Cloud service that allows you to store a large amount of data with high persistence. OSS provides console-independent RESTful API operations for you to store and access data of any type anytime, anywhere, and from any application. API Gateway supports creating an API whose backend service is OSS. When you create an API with OSS as the backend service to perform operations on OSS. You can not only upload objects to, download objects from, and delete objects from your buckets, but also integrate the capabilities of API Gateway to provide more reliable services for your business. In addition, if you activate API Gateway and OSS in the same region, APIs can access OSS over the internal network.

Step 1 Activate OSS

Log on to the Alibaba Cloud console, search for OSS, and then follow the instructions to activate OSS.

Step 2: Create an OSS bucket

For more information about how to create an OSS bucket, see OSS documentation. In this example, set the parameters as required, as shown in the following figure.

Create an OSS bucket

3. Create an API group

APIs are managed in API groups. Before you create an API, you must create an API group.

Step 3: Create an API group

In the left-side navigation pane, choose Open API > Groups. In the top navigation bar, select the region where you want to create an API group. On the API Groups page, click Create Group. In the Create Group dialog box, select your dedicated instance and set the Group Name parameter to testOssGroup. Only dedicated instances of a specific version and later support APIs with OSS as the backend service. If your dedicated instance is of an earlier version, contact Alibaba Cloud technical support to upgrade your instance.

Create an API group

Step 4: View the details of the API group

After you create the API group, the API group appears on the API Groups page. You can click the group name to go to the Group Details page. On this page, you can bind a domain name, modify basic information, and change the instance type.

After an API group is created, API Gateway automatically creates a public second-level domain for the API group. This default second-level domain can be used only to test API calls and can be used for a maximum of 1,000 times per day. We recommend that you bind an independent domain name after you create an API group. In this example, the default second-level domain is used.

4. Create an API

In the left-side navigation pane, choose Open APIs > APIs. Make sure that the current region is the same region where the API group you created resides. On the APIs page, click Create API.

Step 5: Configure basic information for the API

In this step, configure the basic information for the API to be created, including the API group to which the API belongs and the name, authentication method, type, and description of the API. In this example, set the Group parameter to the API group you created and the AppCode Authentication parameter to Enable AppCode Authentication (Header & Query). Set other parameters as required and click Next.

Configure basic information for the API

Step 6: Configure request information for the API

In this step, define how a client, such as a browser, a mobile app, or a business system, sends a request for the API. The parameters that need to be specified in this step include Request Type, Protocol, Request Path, HTTP Method, Request Mode, and the parameters in the Request Parameters section. Then, click Next. In this example, set the HTTP Method parameter to GET, the Request Mode parameter to Pass-through. A value of Pass-through indicates that API Gateway passes the received parameters to the backend service without processing.

Note

Note that the HTTP method that you specify for the API determines the available API operations of OSS. API Gateway supports the GET, PUT, POST, HEAD, and DELETE methods for APIs that use OSS as the backend service. The methods support the following API operations of OSS:

GET: GetObject

PUT: PutObject

POST: PostObject and AppendObject

HEAD: HeadObject and GetObjectMeta

DELETE and DeleteObject

For more information about the description of the API operations, see API Reference of OSS.

Configure request information for the API

Step 7: Configure backend service information for the API

In this step, configure a backend service type and a backend service address of the API and the mappings between request and response parameters. In this example, set the Backend Service Type parameter to OSS. Set the Action parameter to GetObject because GET is specified as the request method in the preceding step. We recommend that you select the region where both OSS and API Gateway reside. In this case, API Gateway can send requests to OSS over the internal network.Configure backend service information for the API

Note

To allow API Gateway to access OSS, you must grant permissions on your OSS bucket to API Gateway as prompted after you configure backend service information.

OSS bucket authorization

In the preceding figure, you can grant the read permissions on the entire bucket or a specific object to API Gateway because you set the Action parameter to GetObject. The read, write, and delete permissions that you can grant vary based on the value of the Action parameter. To remove the granted permissions, perform the following steps: Log on to the OSS console and click your OSS bucket in the left-side navigation pane. In the left-side navigation pane of the bucket details page, click Access Control. On the Access Control page, click Configure in the Bucket Policy section. On the Bucket Policy page, you can remove the granted permissions.

Step 8: Configure response information for the API

In this step, configure response information to generate API documentation. The documentation helps API callers better understand APIs. You can set parameters such as Response ContentType, Response Example, and Error Response Example. In this example, this step is skipped. Click Create.

Step 9: Publish the API

After you click Create, a message appears to inform you that the API is created, as shown in the following figure. API Gateway provides three environments to which you can publish an API: Release, Staging, and Test. All configurations you perform on an API can take effect only after you publish the API to a required environment. In this example, click Publish in the message that indicates successful API creation. In the Publish API dialog box, set the Stage parameter to Release, enter remarks, and then click Publish.

Successful creation

5. Create an APP and grant the APP the permissions to call the API

APPs are the identities that you use to call APIs. In Step 5, the Security Authentication parameter is set to Alibaba Cloud APP. Therefore, after you publish the API, you must create an APP and grant the APP the permissions to call the API.

Step 10: Create an APP

In the left-side navigation pane, choose Call APIs > Apps. On the Apps page, click Create App. In the Create App dialog box, enter an APP name and click Confirm. In the APP list, click the name of the created APP. Two authentication modes are provided: an AppKey and AppSecret pair and AppCode. In this example, the AppCode mode is used to authenticate the APP. For more information about this mode, see Call an API operation by using an AppCode.

Create an APP

Step 11: Grant the APP the permissions to call the API

In the left-side navigation pane, choose Open API > APIs. On the APIs page, find the created API and choose More > Authorize. A dialog box appears, as shown in the following figure. Set the Stage parameter to the environment to which you have published the API. In this example, set this parameter to Release. Enter the name of the APP you created in the search bar of the Choose Apps for Authorization section. In the search result, select the created APP, click Add in the Actions column, and then click Confirm. A message appears to inform you that the APP is authorized to call the API.

Authorize

6. Debug the API

API Gateway supports online debugging. We recommend that you use this feature to check whether an API is correctly configured before you call this API on clients.

Step 12 Debug the API

On the APIs page, click the name of the created API. On the API details page, click Debug API in the left-side navigation pane. The following figure shows the page that appears. If you have defined request parameters for the API, you can enter different values for the request parameters to check whether the API is correctly configured.

When you debug the API, make sure that the App Name parameter is set to the authorized APP. The environment for debugging must be the one where the APP is authorized to call the API. Otherwise, the debugging may fail. In this example, select Release as the environment for debugging.

Successful call

7. Call the API

After you perform the preceding steps, you have created the API and the APP, authorized the APP to call the API, debugged the API, and published the API to the online environment. In this step, you can call the API in your business system by using the AppCode.

Step 13: Call the API

For more information about API calls, see Overview. In this example, the curl command is used to call the API.

The following figure shows the call result.

Successful call