View Source CozyAliyunOpenAPI (cozy_aliyun_open_api v0.1.0)
An SDK builder for Aliyun OpenAPI.
basic-concepts
Basic Concepts
A complete API call will go through the following steps:
- creating a config.
- creating a spec.
- transforming the spec to a HTTP request.
- sending the HTTP request.
a-code-example
A Code Example
alias CozyAliyunOpenAPI.Config
alias CozyAliyunOpenAPI.Specs.RPC
alias CozyAliyunOpenAPI.HTTPRequest
alias CozyAliyunOpenAPI.HTTPClient
# 1. create a config
config =
Config.new!(%{
access_key_id: "...",
access_key_secret: "..."
})
# 2. create a spec
RPC.new!(config, %{
method: :post,
endpoint: "https://ecs-cn-hangzhou.aliyuncs.com/",
shared_params: %{
"Action" => "DescribeInstanceStatus",
"Version" => "2014-05-26"
},
params: %{
"RegionId" => "cn-hangzhou"
}
})
# 3. transform the spec to a HTTP request
|> HTTPRequest.from_spec!()
# 4. send the HTTP request
|> HTTPClient.request()
In order to accommodate as many different usage scenarios as possible,
CozyAliyunOpenAPI
provides only low-level APIs.If you find the API calls are tedious, consider to encapsulate the low-level APIs by yourself.
api-styles
API Styles
For a variety of reasons, Aliyun OpenAPI involves several different API styles:
- RPC
- ROA
- OSS
These different styles of APIs are supported by different spec modules:
authentication-authorization
Authentication & Authorization
required-credentials
required credentials
Authentication can be accomplished in two ways. Different ways require different credentials:
- Access Key ID / Access Key Secret
- Access Key ID / Access Key Secret / STS Token
STS is the shorthand for Security Token Service. It allows developers to manage temporary credentials to resources.
signature-mechanisms
signature mechanisms
When using the credentials, the Access Key Secret shouldn't be sent. Intead, signatures generated in a certain way should be used.
Different API styles use different signature mechanisms. The CozyAliyunOpenAPI.Specs.*
modules
will try their best to include relevant implementations.
authorization
authorization
Before calling any API, please make sure the required permission is granted.
about-endpoints
About Endpoints
In official docs, the term endpoint refers to different things:
- sometimes, it refers to a host, such as
ecs-cn-hangzhou.aliyuncs.com
. - sometimes, it refers to a URL, such as
https://ecs-cn-hangzhou.aliyuncs.com
.
That is annoying.
CozyAliyunOpenAPI
will always use the endpoint to refer to a valid URL:
<protocol>://<host>/<path>?<query>
public-endpoints
public endpoints
- centralized deployments:
<protocol>://<service_code>.aliyuncs.com/
- multi-region deployments:
<protocol>://<service_code>.<region_id>.aliyuncs.com/
private-endpoints-aka-vpc-endpoints
private endpoints (aka VPC endpoints)
Private endpoints are also known as VPC endpoints.
- centralized deployments:
<protocol>://<service_code>.vpc-proxy.aliyuncs.com/
- multi-region deployments:
<protocol>://<service_code>-vpc.<region_id>.aliyuncs.com/
public-endpoints-vs-private-endpoints
public endpoints vs. private endpoints
Public endpoints consume public network traffic.
Private endpoints don't consume public network traffic. In addition, they provide higher network speed, and higher level secure protection.
Personally, I recommend using private endpoints as much as possible.