This topic describes the basic concepts related to Alibaba Cloud. The concepts include cloud service, region, resource, operation, and permission.
Alibaba Cloud APIs are publicly available and are the major method for Alibaba Cloud to deliver service capabilities in addition to consoles. You can use Alibaba Cloud services by using programming methods. Compared with consoles, APIs provide advantages such as large-scale provisioning, automation, and customization. APIs are the best way to integrate your business with cloud services.
Alibaba Cloud provides SDKs and CLIs in multiple programming languages, which simplifies API calls. The programming languages include Java, C#, Go, Python, Node.js, TypeScript, PHP, and C++. Alibaba Cloud also provides tools, such as Terraform and Cloud Development Toolkit (CDK) for Resource Orchestration Service (ROS), to meet your requirements in special scenarios. The SDKs and tools are implemented based on APIs.
Before you can call APIs by using specific tools, you must learn about the basic concepts of APIs. This helps improve development efficiency and experience.
Cloud service
Cloud services are the API-based capabilities that are provided by an Alibaba Cloud service. However, a cloud service is not the same as an Alibaba Cloud service because an Alibaba Cloud service may provide a variety of cloud services. For example, Resource Access Management (RAM) provides two cloud services based on usage. The cloud services are Security Token Service (STS) and Identity Management Service (IMS).
Cloud services cover various fields, such as computing, storage, networking, machine learning, communications, and DevOps. Cloud services are categorized into the following types based on usage:
Management
This type of cloud service allows you to manage resources by calling APIs. This type of cloud service is available in most IaaS services, such as Elastic Compute Service (ECS), Server Load Balancer (SLB), Virtual Private Cloud (VPC), ApsaraDB RDS, and Object Storage Service (OSS).
Capability
This type of cloud service allows you to use the capabilities of Alibaba Cloud services by calling APIs. This type of cloud service is available in Alibaba Cloud services that provide communications features, such as Short Message Service (SMS) and Direct Mail. This type of cloud service is also available in Alibaba Cloud services that provide machine learning features, such as Machine Translation and Face Service.
Supporting
This type of cloud service provides supporting capabilities such as billing, permission management, and auditing.
However, cloud services of an Alibaba Cloud service do not belong to only one category. For example, you can call some API operations of OSS to manage OSS resources. You can also call some API operations of OSS to use the capabilities of OSS.
The requirements to use the cloud services are consistent with those to use consoles. Before you can use cloud services, you must activate the cloud services. Otherwise, an error message is returned because the service is not activated. To meet the requirements for automation, some cloud services are activated by default. You can also use APIs to activate some services.
Region and endpoint
Before you can use cloud services, you must understand how cloud services are deployed. Central deployment means that the cloud services of an Alibaba Cloud service are deployed in one region. Regional deployment means that the cloud services of an Alibaba Cloud service are deployed in multiple regions.
The cloud services have endpoints. You can use the endpoints to call the API operations of the cloud service.
For cloud services that are centrally deployed, the endpoints are in the <service code>.aliyuncs.com format. For example, the endpoint of IMS is ims.aliyuncs.com.
For cloud services that are deployed in multiple regions, the endpoints are in the <service code>.<region id>.aliyuncs.com format. For example, the endpoint of STS in the China (Hangzhou) region is sts.cn-hangzhou.aliyuncs.com, and the endpoint of STS in the China (Beijing) region is sts.cn-beijing.aliyuncs.com.
The endpoints of cloud services are available in OpenAPI Explorer. For example, if you want to view the endpoints of IMS in all regions, visit https://api.aliyun.com/product/Ims#endpoint.
VPC endpoint
When you call APIs, public endpoints are used by default. API calls by using public endpoints consume public bandwidth. Alibaba Cloud provides VPC endpoints. VPC endpoints allow you to call APIs over an internal network, which reduces data transfer costs, accelerates access, and enhances access security. VPC endpoints for cloud services that are centrally deployed are in the <service code>.vpc-proxy.aliyuncs.com format. VPC endpoints for cloud services that are deployed in multiple regions are in the <service code>-vpc.<region id>.aliyuncs.com format. To view the VPC endpoints of cloud services, visit OpenAPI Explorer.
Group
Different API groups are released for a cloud service at different times. For example, the main API group for ECS is named 2014-05-26, which is released during the period around May 26, 2014. API groups that are released in different periods may be or may not be relevant to each other.
Originally, the names of API groups were considered the versions of APIs. However, the name of an API group indicates only the period when the API group is released. If the API of an Alibaba Cloud service is updated, the version number of the API also changes. However, the names of API groups are not related to the version changes of APIs. The names of API groups are used only to identify API groups.
Resource
The APIs of Alibaba Cloud services provide various operations for resources, which is similar to RESTful APIs. You can create, query, modify, and delete resources.
Resource
For example, the main resource of ECS is instances. You can call API operations to create, query, modify or delete an ECS instance.
In most cases, resources are used together. For example, instances must have disks. Some resources such as groups are virtual. For example, a user belongs to a user group, but the user and the user group are independent of each other.
Operation
Each API operation has a type. The type is determined based on the operation that you can perform on resources by calling the API operation. For example, you can query regions by calling the DescribeRegions operation.
The type of each API operation is available in OpenAPI Explorer. The types of APIs are available in ActionTail.
API style
This section is intended for developers who want to develop SDKs.
A set of APIs has a style. A style includes the structure of URLs, format of parameters, and transmission format. RESTful is a common API style. In RESTful APIs, HTTP methods specify actions, paths in URLs specify resources, and data is transmitted in the JSON format.
Alibaba Cloud APIs are used in multiple services and have the following multiple styles:
RPC
ROA
OSS
APIs in an RPC style are in the http://{{Endpoint}}/?Action={{API NAME}} format. APIs in an ROA style are in the http://{{Endpoint}}/{{Resources}} format. ROA APIs are similar to RESTful APIs.
The SDK encapsulation of APIs varies based on the styles of APIs. The SDKs provided by Alibaba Cloud encapsulate the details about the APIs in different styles as much as possible.
Identity, authentication, and permissions
Alibaba Cloud APIs are divided into two types: anonymous APIs and APIs that require identity authentication. If you call an anonymous API, you need to only make sure that your API request is compliant with the style of the API.
If you call an API that requires identity authentication, you must make sure that your identity, authentication, and permissions are valid.
Identity and credential
Alibaba Cloud accounts and RAM users are identities. Cloud services use credentials for authentication.
For example, cloud services use passwords for authentication when you log on to a console. In this case, the email and password are the credentials.
Alibaba Cloud uses AccessKey pairs for authentication when you call APIs. An AccessKey pair consists of an AccessKey ID and an AccessKey secret. To manage your AccessKey pair, go to the RAM console. The AccessKey pair of an Alibaba Cloud account has full permissions. This may cause high security risks if this type of AccessKey pair is leaked. We recommend that you do not use the AccessKey pair of your Alibaba Cloud account. To ensure security, we recommend that you use RAM users instead. RAM users grant fine-grained permissions to implement access control in a fine-grained manner.
Alibaba Cloud also provides temporary STS tokens. An AccessKey pair is valid for a long period of time. However, a temporary STS token is valid only within a specific period to ensure security. An STS token is a 3-tuple of the string type and consists of an AccessKey ID, AccessKey secret, and security token.
An STS token cannot be created. You can obtain an STS token by using the following methods:
Use an instance RAM role of ECS.
Use the Alibaba Cloud Resource Name (ARN) of a RAM role.
Use CloudSSO.
Use a public key certificate and a private key. This method is supported only on the Japan site.
An STS token has a validity period. If you want to use STS tokens in an SDK, the SDK must be able to automatically refresh STS tokens.
Request signatures
When you call an API operation, regardless of whether you use an AccessKey pair or STS token, the AccessKey secret is not published to the gateway for authentication. The request is signed by using asymmetric encryption. The gateway obtains the AccessKey secret based on the obtained AccessKey ID and signs the request. Then, the gateway checks the signature and determines whether the credentials are valid.
For more information about the signature process, see the following topics:
For security reasons, the development process of an API is complex. The development of an API requires three to five days to complete. We recommend that you use the tools provided by Alibaba Cloud, such as SDKs and CLIs. The APIs are encapsulated in the SDKs and CLIs. This allows you to focus only on using the APIs without the need to pay attention to the development process.
Permissions
If your credentials pass the authentication, your identity is valid. However, you cannot call an API only by using valid credentials. To call an API, you must have valid credentials, correctly sign the request, and obtain the required permissions. If you use a RAM user, you can manage the permissions in the RAM console.
The permissions that are required for each API operation are available in OpenAPI Explorer.
Throttling
You must take note of throttling policies for APIs. The throttling for APIs varies based on Alibaba Cloud services. Take note of the maximum number of API requests that can be concurrently initiated to ensure that the call is not interrupted by throttling errors.
The throttling policy for each API is available in OpenAPI Explorer.