1 | # @!title Upgrading Notes (1.x to 2.0)
|
2 |
|
3 | # Upgrading Notes (1.x to 2.0)
|
4 |
|
5 | This document captures breaking changes from 1.x versions to the first
|
6 | stable 2.x (non-RC) release of the AWS SDK for JavaScript.
|
7 |
|
8 | ## 1. Automatic Conversion of Base64 and Timestamp Types on Input/Output
|
9 |
|
10 | The SDK will now automatically encode and decode base64-encoded values, as well
|
11 | as timestamp values, on the user's behalf. This change affects any operation
|
12 | where Base64 or Timestamp values were sent by a request or returned in a
|
13 | response, i.e., `AWS.DynamoDB` and `AWS.SQS`, which allow for Base64
|
14 | encoded values.
|
15 |
|
16 | User code that previously did base64 conversion no longer requires this.
|
17 | Furthermore, values encoded as base64 are now returned as Buffer objects
|
18 | from server responses (and can also be passed as Buffer input). For
|
19 | example, the following 1.x `SQS.sendMessage()` parameters:
|
20 |
|
21 | ```javascript
|
22 | var params = {
|
23 | MessageBody: 'Some Message',
|
24 | MessageAttributes: {
|
25 | attrName: {
|
26 | DataType: 'Binary',
|
27 | BinaryValue: new Buffer('example text').toString('base64')
|
28 | }
|
29 | }
|
30 | };
|
31 | ```
|
32 |
|
33 | Can be rewritten as:
|
34 |
|
35 | ```javascript
|
36 | var params = {
|
37 | MessageBody: 'Some Message',
|
38 | MessageAttributes: {
|
39 | attrName: {
|
40 | DataType: 'Binary',
|
41 | BinaryValue: 'example text'
|
42 | }
|
43 | }
|
44 | };
|
45 | ```
|
46 |
|
47 | And the message will be read as:
|
48 |
|
49 | ```javascript
|
50 | sqs.receiveMessage(params, function(err, data) {
|
51 | // buf is <Buffer 65 78 61 6d 70 6c 65 20 74 65 78 74>
|
52 | var buf = data.Messages[0].MessageAttributes.attrName.BinaryValue;
|
53 | console.log(buf.toString()); // "example text"
|
54 | });
|
55 | ```
|
56 |
|
57 | ## 2. Moved response.data.RequestId to response.requestId
|
58 |
|
59 | The SDK now stores request IDs for all services in a consistent place on the
|
60 | response object, rather than inside the response.data property. This is to
|
61 | improve consistency across services that expose request IDs in different ways.
|
62 | Note that this is also a breaking change that renames the
|
63 | `response.data.RequestId` property to `response.requestId`
|
64 | (or `this.requestId` inside of a callback).
|
65 |
|
66 | To migrate your code, change:
|
67 |
|
68 | ```javascript
|
69 | svc.operation(params, function (err, data) {
|
70 | console.log('Request ID:', data.RequestId);
|
71 | });
|
72 | ```
|
73 |
|
74 | To the following:
|
75 |
|
76 | ```javascript
|
77 | svc.operation(params, function () {
|
78 | console.log('Request ID:', this.requestId);
|
79 | });
|
80 | ```
|
81 |
|
82 | ## 3. Exposed Wrapper Elements
|
83 |
|
84 | If you use {AWS.ElastiCache}, {AWS.RDS}, or {AWS.Redshift}, you must now access
|
85 | the response through the top-level output property in the response for certain
|
86 | operations. This change corrects the SDK to behave according to documentation
|
87 | output, which was previously listing this wrapper element.
|
88 |
|
89 | Example:
|
90 |
|
91 | `RDS.describeEngineDefaultParameters()` used to return:
|
92 |
|
93 | ```javascript
|
94 | { Parameters: [ ... ] }
|
95 | ```
|
96 |
|
97 | This operation now returns:
|
98 |
|
99 | ```javascript
|
100 | { EngineDefaults: { Parameters: [ ... ] } }
|
101 | ```
|
102 |
|
103 | The full list of affected operations for each service are:
|
104 |
|
105 | **AWS.ElastiCache**: authorizeCacheSecurityGroupIngress, createCacheCluster,
|
106 | createCacheParameterGroup, createCacheSecurityGroup, createCacheSubnetGroup,
|
107 | createReplicationGroup, deleteCacheCluster, deleteReplicationGroup,
|
108 | describeEngineDefaultParameters, modifyCacheCluster, modifyCacheSubnetGroup,
|
109 | modifyReplicationGroup, purchaseReservedCacheNodesOffering, rebootCacheCluster,
|
110 | revokeCacheSecurityGroupIngress
|
111 |
|
112 | **AWS.RDS**: addSourceIdentifierToSubscription, authorizeDBSecurityGroupIngress,
|
113 | copyDBSnapshot, createDBInstance, createDBInstanceReadReplica,
|
114 | createDBParameterGroup, createDBSecurityGroup, createDBSnapshot,
|
115 | createDBSubnetGroup, createEventSubscription, createOptionGroup,
|
116 | deleteDBInstance, deleteDBSnapshot, deleteEventSubscription,
|
117 | describeEngineDefaultParameters, modifyDBInstance, modifyDBSubnetGroup,
|
118 | modifyEventSubscription, modifyOptionGroup, promoteReadReplica,
|
119 | purchaseReservedDBInstancesOffering, rebootDBInstance,
|
120 | removeSourceIdentifierFromSubscription, restoreDBInstanceFromDBSnapshot,
|
121 | restoreDBInstanceToPointInTime, revokeDBSecurityGroupIngress
|
122 |
|
123 | **AWS.Redshift**: authorizeClusterSecurityGroupIngress, authorizeSnapshotAccess,
|
124 | copyClusterSnapshot, createCluster, createClusterParameterGroup,
|
125 | createClusterSecurityGroup, createClusterSnapshot, createClusterSubnetGroup,
|
126 | createEventSubscription, createHsmClientCertificate, createHsmConfiguration,
|
127 | deleteCluster, deleteClusterSnapshot, describeDefaultClusterParameters,
|
128 | disableSnapshotCopy, enableSnapshotCopy, modifyCluster,
|
129 | modifyClusterSubnetGroup, modifyEventSubscription,
|
130 | modifySnapshotCopyRetentionPeriod, purchaseReservedNodeOffering, rebootCluster,
|
131 | restoreFromClusterSnapshot, revokeClusterSecurityGroupIngress,
|
132 | revokeSnapshotAccess, rotateEncryptionKey
|
133 |
|
134 | ## 4. Dropped `.Client` and `.client` Properties
|
135 |
|
136 | The `.Client` and `.client` properties have been removed from Service objects.
|
137 | If you are using the `.Client` property on a Service class or a `.client`
|
138 | property on an instance of the service, remove these properties from your code.
|
139 |
|
140 | Upgrading example:
|
141 |
|
142 | The following 1.x code:
|
143 |
|
144 | ```
|
145 | var sts = new AWS.STS.Client();
|
146 | // or
|
147 | var sts = new AWS.STS();
|
148 |
|
149 | sts.client.operation(...);
|
150 | ```
|
151 |
|
152 | Should be changed to the following:
|
153 |
|
154 | ```
|
155 | var sts = new AWS.STS();
|
156 | sts.operation(...)
|
157 | ```
|