SDK

General Reference

https://docs.aws.amazon.com/general/latest/gr/Welcome.html

Contents:

• Region & Endpoints
• Security credentials
• ARN format & name spaces
• Signing request
• Service Limits
• IP Address ranges
• Retries
  • Each AWS SDK implements automatic retry logic (see SDK configuration)
  • What to retry (general)
    • 5xx or throttle errors from server
    • NOT 4xx errors (client error, revise request)
  • Each AWS SDK implements exponential backoff algorithm, with jitter (random) to avoid conflict. https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
  • To debug and inspect retries, AWS.events.on('retry', function(resp){...
• S3 Clientside Encryption

SDK for Javascript

https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/welcome.html

Basics

For Node.js (EC2, Lambda), for browser. Amplify extends SDK for browser and provides declarative interface.

Setup

Node.js:

• EC2 container - choose an image with the environment
• EC2 - install
• Lambda - already provided

Browser:

• Can build a smaller one for selected services only
• CORS:
  • Many services (S3) requires CORS configuration on resources

Configuration

Minimum - region & credentials (note: if load from user shared config, credentials could be null if resume role, it only become available after actually used)

How to configure:

• using the global configuration object (for every service)
  • AWS.config.update({region:'...
  • Environment variable like AWS_REGION
  • loading shared config & credential from ~/.aws (see below)
• configure per service class (for all instances hereafter)
  • AWS.config.ec2 = {region: 'us-west-2', apiVersion: '2016-04-01'};
• or pass extra configuration to service object when creating them (take all the configuration parameters as the global configuration including region & credentials).
  • new AWS.SomeService({...
• load from user shared config & credentials (default in ~/.aws dir) (see here)

# from shell

export AWS_SDK_LOAD_CONFIG=true

export AWS_PROFILE=default

# also AWS_REGION 

# see https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-region.html

# see https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/loading-node-credentials-shared.html

or

process.env.AWS_SDK_LOAD_CONFIG = true; 

const AWS = require('aws-sdk');

Examples: using cognito ID pool

AWS.config.region = ...

// from cognito ID pool

AWS.config.credentials = new AWS.CognitoIdentityCredentials({...

// another style

var myCredentials = new AWS.CognitoIdentityCredentials({IdentityPoolId:'IDENTITY_POOL_ID'});

var myConfig = new AWS.Config({

  credentials: myCredentials, region: 'us-west-2'

});

// using 'update' 

myConfig = new AWS.Config();

myConfig.update({region: 'us-east-1'});

Example: per-service instance

var ec2_regionA = new AWS.EC2({region: 'ap-southeast-2', maxRetries: 15, apiVersion: '2014-10-01'});

var ec2_regionB = new AWS.EC2({region: 'us-east-1', maxRetries: 15, apiVersion: '2014-10-01'});

API Version Lockup

API version identified by 'YYYY-MM-DD'

Locking up recommended in production environment.

To lockup, do it individually when instantiating service object, or globally:

AWS.config.apiVersions = {

   dynamodb: '2011-12-05',

   ec2: '2013-02-01',

   redshift: 'latest'

};

Work with Services

Importing the service class:

• require('aws-sdk') get everything
• require('aws-sdk/clients/SERVICE') get individual service + require('aws-sdk/global') get the global namespace, smaller footage doing things this way

Creating service object:

• Pass configurations for the object (override global configurations)
• Pass {params:{ someParameter: 'someDefaultValue'}} then the parameter would not be needed to be provided with every invocation (unless for overriding)

Invoking a service include full request / response & retry

AWS.Request / AWS.Response object encapsulates the request & responses.

Logging - see document

Asynchronous calling

• All calls asynchronous
• Manners:
  • Pass callback as last parameter in service method calls
    • function(error, data) {...} (not arrow style)
    • "this" in callback for most services refer to the Response object, and through it can then refer to the Request object
    • In this manner the call is sent out
  • No callback parameter, register callback
    • Without callback passed in, method calls return the Request object
    • Must manually call .send() method
    • Register callbacks (multiple) before send
      • ... request.on('success', function(response) {...})
      • can chain up ".on(...).on(...).send()"
      • common callbacks:
        • 'success', function(response)
        • 'error', function(error,response)
        • 'complete', function(response){ if (response.error)...
  • Use promises (after calling a service method without callback to obtain a Request not sent yet)
    • var promise = request.promise(); - immediately send and obtain the promise
  • Request with Stream (file downloading with S3, etc.) see document

Response Object

• properties "error" & "data"

Retry

See https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html#retryDelayOptions-property

Someone said most services by default retry 3 times, while DynamoDB retry 10 times (can be set).

Set maximum retries globally: AWS.config.maxRetries = 5

Set for individual service (DynamoDB): new AWS.DynamoDB({maxRetries: 5})

Inspect & diagnose:

On global level

AWS.events.on('retry', function(resp) {

  if (resp.error && resp.error.retryable) {

    var date = new Date();

    console.log(date, '| Retrying request for the ' + resp.retryCount + 'th time.');

    console.log(date, '| Retry triggered by', err.code, err.message);

  }

}); 

On individual request level

req.on('retry', function() { ... });