Alibaba Cloud API Gateway Manual de usuario
API Gateway
User Guide for Providers
User Guide for Providers
Overview
API Gateway provides high-performance and highly available API hosting service to help users to
publish or access to the APIs on Alibaba Cloud products such as ECS and Container Service. It
manages the entire API lifecycle from release and management to maintenance. You can quickly
open data or services at low costs and risks through simple operations.
API Gateway provides the following features:
API management
You can manage the lifecycle of an API, including creation, testing, release, deprecation, and
version switching.
Easy data conversion
You can configure a mapping rule to convert the calling request into the format required by
the backend.
Presetting of request verification
You can preset the verification of the parameter type and values (range, enumeration,
regular expression, and JSON Schema) for gateway to preclude the invalid requests, reduce
the utilization rate of your backend.
Flexible throttling
You can set throttling for APIs, users, and APPs by minute, hour, or day.
In addition, you can also specialize some users or APPs with the independent throttling.
Easy security protection
API Gateway supports AppKey authentication and HMAC (SHA-1,SHA-256) signature.
API Gateway User Guide for Providers
1
1.
2.
3.
1.
API Gateway supports SSL/TSL encryption and uses Alibaba Cloud Security to prevent
viruses and attacks.
Comprehensive monitoring and warning
API Gateway provides visualized API monitoring in real time, including the calling traffic,
calling method, response time, and error rate, and supports query of historical records for
comprehensive analysis. You can also configure and subscribe to the warning method (SMS
or email) to check the API running status in real time.
Lower cost of publication
API Gateway automatically generates API documentation and SDKs (service end and mobile
end), reducing the cost of publication of API.
Create an API
API creation is a process to define an API request. When creating an API, you must define the format
of API call requests, the format of requests sent from the gateway to backend services, the format of
returned results, the parameter verification rules and so on.
Define basic information
Basic API information includes the API group, API name, description, and API type.
Select an API group when creating an API. An API group is a management unit of APIs with
a corresponding region and domain name (for more information about the API group, see
the description of groups and domain names as follows). APIs in an API group share the
same region and domain name. Once selected, the group cannot be changed.
The API name must be unique in the group and cannot be changed.
Two types of APIs are required: public and private, which have no substantial difference at
the public beta stage.
Define backend service information
Information of API backend services includes the type, address, and time-out time of backend
services.
Backend service type. Only HTTP service is supported now, and Sigma, Mock, and other
types of services will be supported in the future.
API Gateway User Guide for Providers
2
2.
3.
Backend service address. It is the complete IP address used by the API Gateway to call
underlying services, which includes a domain name/IP+Path without Query parameter. It
may contain dynamic parameters, such as username (written as username), and could be
obtained only through the path entered by the caller. Therefore, do not omit these dynamic
parameters when defining the final path.
Backend time-out time. It is the response time for beckend service to return the results after
receiving requests from the gateway. The time-out time must not exceed 30 seconds.
Define the API request format
The API request format definition includes protocol and method definition, path definition, input
parameter definition, system parameter definition, parameter mapping, and parameter verification
definition.
Protocol and method definition. HTTP/HTTPS protocols are supported for API calling.
Methods include PUT, GET, POST, DELETE, HEAD, and MULITIPART.
Path definition. It is the path used by the caller to call the API available to external resources.
The gateway stores the corresponding relations and locates the corresponding paths. The
path may differ from that in the backend service address. You have to map the parameters
when defining the path if they are in the backend service address.
Input parameter definition. The parameters to input conprise header, query, and body. You
must define the name of the input parameter of the user request. Choose the required
parameters, and provide the example value, default value and description. The types of
parameters include String, Number, Boolean and JSON. The transmission mode of the body
parameter may be transparent transmission.
Parameter verification definition. When defining the input parameters, you can click More to
set verification for the parameter, including verification of the enumeration value, the string
length, and the maximum and minimum values of the number. The gateway intercepts
invalid requests, relieving burdens of your backend services.
Parameter mapping. To guise your auctual parameter name of your backend service, you can
configure a backend parameter mapping for each parameter when defining the parameter.
System parameter definition. System parameters are invisible to API callers. Two types of
system parameter are required, one of which that is transmitted by the gateway to you is
described in the following table:
Name Meaning
CaClientIp The clien IP address which sends the
request
API Gateway User Guide for Providers
3
When creating an API, you must configure the system parameter and select parameter
position and backend parameter name.
The other type is custom system parameter required by your API backend service. It may be
a constant parameter. The configuration includes the parameter value, backend parameter
name, and the parameter position in the request.
Returned result definition. It is the type and example of returned results. Currently, the
gateway does not process returned results.
Note: You must enter the dynamic parameters in the path, headers parameter, query parameter,
body parameter (non-binary), constant parameter, and system parameter. The parameter name must
be globally unique. It is not allowed to enter a parameter named “name” in headers and queries at
the same time.
After the preceding steps, now you can test and release the API, grant permissions to your customers,
bind a signature key and throttling policy to the API, and perform other security configurations.
Enable API services
Enable API services
This section provides information you must understand for the API group and domain name before
you enable API services.
CaDomain The domain name which sends the
request
CaRequestHandleTime Request time (Greenwich mean time)
CaAppId ID of the app which sends the request
CaRequestId RequestId
CaApiName API name
CaHttpSchema The protocol (HTTP or HTTPS) used by
the user to call the API
CaProxy Proxy (AliCloudApiGateway)
API Gateway User Guide for Providers
4
-
-
API group
An API group is the management unit of APIs. You must create a group before creating an API. The
group consists of four attributes: name, description, region, and domain name. Note that:
The group region is fixed once selected.
Each account can have up to 50 API groups and each API group can have up to 200 APIs.
When you create a group, the system assigns the group a second-level domain name to test
your API. To enable the API service, you must bind the group to an independent domain
name filed on Alibaba Cloud and resolve the CNAME of the independent domain name to
the second-level domain name of the group. Up to five independent domain names can be
bound to a group.
Domain name and certificate
API Gateway locates the unique API group through the domain name, and the unique API through
the Path+HTTPMethod. Before enabling API services, you must know the second-level domain name
and independent domain name as follows:
The unique and fixed second-level domain name is assigned by the system during group
creation. By default, a second-level domain name is used to call the API only in the test
environment under a small amount of traffic.
An independent domain name is used for enabling API services. You can bind up to five
independent domain names to a group. When configuring independent domain names, pay
attention to the following points:
Resolve the CNAME of an independent domain name to the API second-level
domain name of the group before binding the API group and domain name.
Verify the domain name within one day. Otherwise, the unprocessed binding
request is automatically withdrawn by the system.
If a domain name is already bound to another group, resolve the domain name to
the second-level domain name of the to-be-bound group before binding.
Otherwise, the binding fails.
If your API supports the HTTPS protocol, you must upload the SSL certificate of the domain name by
entering the parameters on the Group Details page, including the name, content, and private key.
API Gateway User Guide for Providers
5
-
-
-
1.
2.
3.
1.
2.
3.
Test, production, and authorization
To test or enable the API, authorization is indispensable. Authorization means granting an app the
permission to call an API. Note that:
You can authorize the created app and access the second-level domain name to call the API.
You can authorize the apps of customers to access the independent domain name to call
your API service.
Only an authorized app can call the API.
Now you have successfully enabled your API service. From creating the API to enabling it, you can
create, modify, delete, view, test, release, remove, authorize, and revoke the authorization of an API.
You can also view the release history and switch the version.
Manage an API
API definitions refer to the definitions related to the API request structure when you create an API.
You can view, edit, delete, create, or copy an API definition on the console. Pay attention to the
following points when you are working with API definitions:
Editing the definition of a released API does not affect the definition in the production
environment unless you release and synchronize it to the production environment.
It is not allowed to directly delete the API definition. Deprecate the API definition before
deleting it.
You can copy the definition from the test/production environment to overwrite the latest
definition, and then, if needed, click Edit to modify the definition.
API release management
You can release or deprecate an API in a test or production environment with the following
attentions:
You can access the second-level domain name or independent domain name to call the API
that is released to the test or production environment.
The latest released version of an API overwrites the preceding version in the
test/production environment and takes effect in real time.
When you deprecate an API in the test/production environment, the binding policy, keys,
app, and authorization persists are automatically deprecated unless the API is released to
production again. To revoke this relationship, you must delete it.
API Gateway User Guide for Providers
6
1.
2.
3.
4.
1.
2.
3.
API authorization management
You can establish or revoke the authorization relationship between an API and an app. API Gateway
verifies the permission relationship. During authorization, pay attention to the following points:
You can authorize one or more APIs to one or more apps. We recommend that you do not
operate APIs in multiple groups at the same time during batch operation.
During batch operation, select an API and related environment. For example, if an API has
been released to both the test and production environments, but only the test environment
is chosen, only the API in the test environment is authorized.
You can locate an app based on the AppID or Alibaba Mail account provided by the
customer.
When you need to revoke the authorization for an app under an API, you can view the API
authorization list and delete the app from the list.
Release history and version switching
You can view the release history of each of you APIs, including the version number, notes,
test/production, and time of each release.
When viewing the release history, you can select a version and switch to it. The new version directly
overwrites the previous one and takes effect in real time.
Backend Signature
What Is a Signature Key
A signature key is the Key-Secret pair you create, based on which the backend service verifies the
request received from the gateway. Pay attention to the following points:
An unchangable region must be selected during key creation. The key can only be bound to
APIs in the same region.
One API can be bound with only one key. The key can be replaced, modified, bound to, or
unbound from the API.
After binding a key to an API, the signature information is added to all the requests sent
from the gateway to the API at your service backend. You must resolve the signature
information through symmetric calculation at the backend to verify the gateway’s identity.
For more information about adding signature to the HTTP service, see Backend HTTP
Service Signature.
API Gateway User Guide for Providers
7
1.
2.
Modify or Replace the Leaked Key
To modify the Key-Secret pair once a key is leaked or to substitute a key bound to an API with
another key, proceed the following steps:
Configure the backend to support two keys: the original key and to-be-modified or
replaced key, so that the request during the switching process can pass signature
verification regardless the key modification or replacement.
After the backend is configured, modify the key. Verify that the new Key and Secret take
effect and delete the leaked or obsolete key.
Throttling
What is throttling policy
You can set throttling for APIs, users, and apps by minute, hour, or day, or you can sort out the
specific users or apps with designated throttling policy. The throttling policy is described as follows:
Throttling policy contains the following dimensions:
The three values can be set in one throttling policy. Note that the user traffic limit
API traffic limit
The call times within a unit time for the
API bound by the policy must not exceed
the set value. The time unit may be
minute, hour, or day, for example, 5,000
times per minute.
App traffic limit
The call times called by each app within a
unit time for an API bound to the policy
must not exceed the set value, for
example, 50,000 times per hour.
User traffic limit
The call times called by each Alibaba
Cloud account within a unit time must
not exceed the set value. An Alibaba
Cloud account may have multiple apps.
The traffic limit for an Alibaba Cloud
account is exactly the limit on the total
traffic of all apps in this account. For
example, the traffic may be 500,000 times
per day.
API Gateway User Guide for Providers
8
must not exceed the API traffic limit, and the app traffic limit must not exceed the
user traffic limit.
In addition, you can set an additional threshold value as the traffic limit value (not
allowed to exceed the value of API traffic limit) for special apps or users. However,
the basic app traffic limit and user traffic limit settings in the throttling policy are no
longer applicable to the special apps or users.
An unchangable region must be selected for the throttling policy, and the throttling policy
can only be applied to APIs in the same region.
The traffic of a single IP address is restricted within 100 QPS regarding with the value of API
traffic limit.
A throttling policy can be bound to multiple APIs, with the limit value and special object
settings appliable to each API separately. The lattest policy bound to the API overwrites the
previous one and takes effect immediately.
To add a special app or user, you must obtain the app ID (AppID) or the Alibaba Mail
account of the user.
On the API Gateway console, you can create, modify, delete, view, bind, and unbind a
throttling policy.
Monitoring and warning
The API Gateway console provides visualized API monitoring and warning in real time. You can obtain
the calling status of an API, including the calling traffic, calling method, response time, and error rate.
API Gateway displays data statistics on the calling status from multiple dimensions in multiple time
units, and supports query of historical data for comprehensive analysis.
You can also configure the warning method (SMS or email) and subscribe to warning information to
know the API running status in real time.
API Gateway User Guide for Providers
9
Tabla de contenidos
Otros manuales de Puerta de Alibaba Cloud
Manuales populares de Puerta de otras marcas
LST
LST M500RFE-AS Manual de usuario
Kinnex
Kinnex Media Gateway Manual de usuario
2N Telekomunikace
2N Telekomunikace 2N StarGate Manual de usuario
Mitsubishi Heavy Industries
Mitsubishi Heavy Industries Superlink SC-WBGW256 Manual de usuario
ZyXEL Communications
ZyXEL Communications ZYWALL2 ET 2WE Manual de usuario
Telsey
Telsey CPVA 500 - SIP Manual de usuario
