Skip to content

Commit 4825a40

Browse files
AllanZhengYPAllanZhengYP
committed
docs: add v2 to v3 changes note
1 parent e352a13 commit 4825a40

File tree

2 files changed

+188
-0
lines changed

2 files changed

+188
-0
lines changed

‎README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,10 @@ In the above example, we’re adding a middleware to our DynamoDB client’s mid
133133
The first argument is a function that accepts next, the next middleware in the stack to call, and context, an object that contains some information about the operation being called.
134134
It returns a function that accepts args, an object that contains the parameters passed to the operation and the request, and returns the result from calling the next middleware with args.
135135

136+
#### Other Changes
137+
138+
If you are looking for a breakdown of the API changes from v2 to v3, we have them listed in [UPGRADING.md](./UPGRADING.md).
139+
136140
### Install from Source
137141

138142
All clients have been published to NPM and can be installed as described above. If you want to play with latest clients, you can build from source as follows:

‎UPGRADING.md

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# Upgrading Notes (2.x to 3.x)
2+
3+
This document captures notable changes from v2 SDK to v3 SDK, as known as modular JavaScript SDK for AWS.
4+
5+
Because v3 is a modular rewrite of v2, some basic conceptions are different between v2 and v3. You can learn about
6+
these changes in our fast growing list of [blog posts](https://aws.amazon.com/blogs/developer/category/developer-tools/aws-sdk-for-javascript-in-node-js/). Among the blog posts, The following 2 will get you up-to-speed:
7+
8+
- [modular packages](https://aws.amazon.com/blogs/developer/modular-packages-in-aws-sdk-for-javascript/)
9+
- [middleware stack](https://aws.amazon.com/blogs/developer/first-class-typescript-support-in-modular-aws-sdk-for-javascript/)
10+
11+
Bellow are a summary of interface changes from v2 to v3 SDK. The goal is to help you easily find the v3 equivalents of
12+
the v2 APIs you are already familiar with.
13+
14+
## Client Constructors
15+
16+
This list is indexed by [parameters in v2 SDK](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html). For
17+
options shown as `Planned` in v3, they are confirmed to be supported, but no timeline can be shared at the moment. They
18+
might not have the same name either.
19+
20+
- [`computeChecksums`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#computeChecksums-property)
21+
- **v2**: Whether to compute MD5 checksums for payload bodies when the service accepts it (currently supported in S3
22+
only).
23+
- **v3**: Not available. Planned.
24+
- [`convertResponseTypes`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#convertResponseTypes-property)
25+
- **v2**: Whether types are converted when parsing response data.
26+
- **v3**: **Deprecated**. This option is considered not type-safe because it doesn't convert the types like time stamp
27+
or base64 binaries from the JSON response.
28+
- [`correctClockSkew`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#correctClockSkew-property)
29+
- **v2**: Whether to apply a clock skew correction and retry requests that fail because of an skewed client
30+
clock.
31+
- **v3**: **Deprecated**. SDK _always_ applies a clock skew correction.
32+
- [`systemClockOffset`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#systemClockOffset-property)
33+
- **v2**: An offset value in milliseconds to apply to all signing times.
34+
- **v3**: No change.
35+
- [`credentials`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#credentials-property)
36+
- **v2**: The AWS credentials to sign requests with.
37+
- **v3**: No change. It can also be an async function that returns a credential.
38+
See [v3 reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/interfaces/_aws_sdk_middleware_signing.awsauthinputconfig-1.html#credentials)
39+
- [`endpointCacheSize`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#endpointCacheSize-property)
40+
- **v2**: The size of the global cache storing endpoints from endpoint discovery operations.
41+
- **v3**: Not available. Planned. This option configures endpoint discovery behavior, which is not yet available in v3.
42+
- [`endpointDiscoveryEnabled`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#endpointDiscoveryEnabled-property)
43+
- **v2**: Whether to call operations with endpoints given by service dynamically.
44+
- **v3**: Not available. Planned. This option configures endpoint discovery behavior, which is not yet available in v3.
45+
- [`hostPrefixEnabled`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#hostPrefixEnabled-property)
46+
- **v2**: Whether to marshal request parameters to the prefix of hostname.
47+
- **v3**: **Deprecated**. SDK _always_ injects the hostname prefix when necessary.
48+
- [`httpOptions`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#httpOptions-property)
49+
50+
A set of options to pass to the low-level HTTP request. These options are aggregated differently in V3. You can
51+
configure them by supplying a new `requestHandler`. Here's the example of setting http options in Node.js runtime. You
52+
can find more in [v3 reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/classes/_aws_sdk_node_http_handler.nodehttphandler-1.html).
53+
54+
```javascript
55+
const { Agent } = require("https");
56+
const { Agent: HttpAgnet } = require("http");
57+
const { NodeHttpHandler } = require("@aws-sdk/node-http-handler");
58+
const dynamodbClient = new DynamoDBClient({
59+
requestHandler: new NodeHttpHandler({
60+
httpsAgent: new Agent({
61+
/*params*/
62+
}),
63+
httpAgent: new HttpAgnet({
64+
/*params*/
65+
}),
66+
connectionTimeout: /*number in milliseconds*/
67+
socketTimeout: /*number in milliseconds*/
68+
}),
69+
});
70+
```
71+
72+
If the client is suppose to run in browsers, a different set of options is available. You can find more in [v3
73+
reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/classes/_aws_sdk_fetch_http_handler.fetchhttphandler-1.html).
74+
75+
```javascript
76+
const { FetchHttpHandler } = require("@aws-sdk/fetch-http-handler");
77+
const dynamodbClient = new DynamoDBClient({
78+
requestHandler: new FetchHttpHandler({
79+
requestTimeout: /*number in milliseconds*/
80+
}),
81+
});
82+
```
83+
84+
Each option of `httpOptions` is specified bellow:
85+
86+
- `httpOptions.proxy`
87+
- **v2**: The URL to proxy requests through
88+
- **v3**: You can set up a proxy with an agent following [this guide](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/node-configuring-proxies.html)
89+
- `agent`
90+
91+
- **v2**: The Agent object to perform HTTP requests with. Used for connection pooling.
92+
- **v3**: You can configure `httpAgent` or `httpsAgent` like in the examples above.
93+
94+
- `connectionTimeout`
95+
- **v2**: Sets the socket to timeout after failing to establish a connection with the server after connectTimeout
96+
milliseconds.
97+
- **v3**: `connectionTimeout` is available [in `NodeHttpHandler` options](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/classes/_aws_sdk_node_http_handler.nodehttphandler-1.html).
98+
- `timeout`
99+
- **v2**: The number of milliseconds a request can take before automatically being terminated.
100+
- **v3**: Hard request timeout is not available in `NodeHttpHandler`, but available as `requestTimeout` [in
101+
`FetchHttphandler` in browsers](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/classes/_aws_sdk_fetch_http_handler.fetchhttphandler-1.html)
102+
- `xhrAsync`
103+
- **v2**: Whether the SDK will send asynchronous HTTP requests.
104+
- **v3**: **Deprecated**. Requests are _always_ asynchronous.
105+
- `xhrWithCredentials`
106+
- **v2**: Sets the "withCredentials" property of an XMLHttpRequest object.
107+
- **v3**: Not available. SDK inherits [the default fetch configurations](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)
108+
109+
- [`logger`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#logger-property)
110+
- **v2**: An object that responds to .write() (like a stream) or .log() (like the console object) in order to log information about requests.
111+
- **v3**: No change. More granular logs are available in v3.
112+
- [`maxRedirects`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#maxRedirects-property)
113+
- **v2**: The maximum amount of redirects to follow for a service request.
114+
- **v3**: **Deprecated**. SDK _does not_ follow redirects to avoid unintentional cross-region requests.
115+
- [`maxRetries`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#maxRetries-property)
116+
- **v2**: The maximum amount of retries to perform for a service request.
117+
- **v3**: Changed to `maxAttempts`. See more in [v3 reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/interfaces/_aws_sdk_middleware_retry.retryinputconfig-2.html#maxattempts). Note that the `maxAttempt` should be `maxRetries` + 1.
118+
- [`paramValidation`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#paramValidation-property)
119+
- **v2**: Whether input parameters should be validated against the operation description before sending the request.
120+
- **v3**: **Deprecated**. SDK _does not_ do validation on client-side at runtime.
121+
- [`region`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#region-property)
122+
- **v2**: The region to send service requests to.
123+
- **v3**: No change. It can also be an async function that returns a region string.
124+
- [`retryDelayOptions`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#retryDelayOptions-property)
125+
- **v2**: A set of options to configure the retry delay on retryable errors.
126+
- **v3**: **Deprecated**. SDK supports more flexible retry strategy with `retryStrategy` client constructor option. See
127+
more [in v3 reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/interfaces/_aws_sdk_types.retrystrategy-1.html)
128+
- [`s3BucketEndpoint`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3BucketEndpoint-property)
129+
- **v2**: Whether the provided endpoint addresses an individual bucket (false if it addresses the root API endpoint).
130+
- **v3**: Renamed to `bucketEndpoint`
131+
- [`s3DisableBodySigning`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3DisableBodySigning-property)
132+
- **v2**: Whether to disable S3 body signing when using signature version v4.
133+
- **v3**: Renamed to `applyChecksum`
134+
- [`s3ForcePathStyle`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3ForcePathStyle-property)
135+
- **v2**: Whether to force path style URLs for S3 objects.
136+
- **v3**: Renamed to `forcePathStyle`
137+
- [`s3UseArnRegion`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3UseArnRegion-property)
138+
- **v2**: Whether to override the request region with the region inferred from requested resource's ARN.
139+
- **v3**: Renamed to `useArnRegion`
140+
- [`s3UsEast1RegionalEndpoint`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#s3UsEast1RegionalEndpoint-property)
141+
- **v2**: When region is set to 'us-east-1', whether to send s3 request to global endpoints or 'us-east-1' regional
142+
endpoints.
143+
- **v3**: **Deprecated**. S3 client will always use regional endpoint if region is set to `us-east-1`. You can set the
144+
region to `aws-global` to send requests to S3 global endpoint.
145+
- [`signatureCache`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#signatureCache-property)
146+
- **v2**: Whether the signature to sign requests with (overriding the API configuration) is cached.
147+
- **v3**: **Deprecated**. SDK _always_ caches the hashed signing keys.
148+
- [`signatureVersion`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#signatureVersion-property)
149+
- **v2**: The signature version to sign requests with (overriding the API configuration).
150+
- **v3**: **Deprecated**. Signature V2 supported in v2 SDK has been deprecated by AWS. v3 _only_ supports signature v4.
151+
- [`sslEnabled`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#sslEnabled-property)
152+
- **v2**: Whether SSL is enabled for requests.
153+
- **v3**: Renamed to `tls`.
154+
- [`stsRegionalEndpoints`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#stsRegionalEndpoints-property)
155+
- **v2**: Whether to send sts request to global endpoints or regional endpoints.
156+
- **v3**: **Deprecated**. STS client will _always_ use regional endpoints if set to a specific region. You can set the
157+
region to `aws-global` to send request to STS global endpoint.
158+
- [`useAccelerateEndpoint`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#useAccelerateEndpoint-property)
159+
- **v2**: Whether to use the Accelerate endpoint with the S3 service.
160+
- **v3**: No change.
161+
162+
## S3 Multipart Upload
163+
164+
In v2, the S3 client contains an [`upload()`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#upload-property)
165+
operation that supports uploading large objects with [multipart upload feature offered by S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html).
166+
167+
In v3, [`@aws-sdk/lib-storage` package](https://github.com/aws/aws-sdk-js-v3/blob/main/lib/lib-storage) is available.
168+
It supports all the features offered in v2 `upload()`, and supports both Node.js and browsers runtime.
169+
170+
## S3 Presigned URL
171+
172+
In v2, the S3 client contains [`getSignedUrl()`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getSignedUrl-property)
173+
and [`getSignedUrlPromise()`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getSignedUrlPromise-property)
174+
operations to generate an URL that users can use to upload or download objects from S3.
175+
176+
In v3, [`@aws-sdk/s3-request-presigner` package](https://github.com/aws/aws-sdk-js-v3/tree/main/packages/s3-request-presigner)
177+
is available. You don't have to differentiate `getSignedUrl()` and `getSignedUrlPromise()` any more. We also have [a blog](https://aws.amazon.com/blogs/developer/generate-presigned-url-modular-aws-sdk-javascript/)
178+
discussing the details of this package.
179+
180+
<!---
181+
## DynamoDB Document Client
182+
183+
TBD
184+
-->

0 commit comments

Comments
 (0)