Menu
AWS Storage Gateway
User Guide (API Version 2013-06-30)

API Reference for AWS Storage Gateway

In addition to using the console, you can use the AWS Storage Gateway API to programmatically configure and manage your gateways. This section describes the AWS Storage Gateway operations, request signing for authentication and the error handling. For information about the regions and endpoints available for AWS Storage Gateway, see Regions and Endpoints.

Note

You can also use the AWS SDKs when developing applications with AWS Storage Gateway. The AWS SDKs for Java, .NET, and PHP wrap the underlying AWS Storage Gateway API, simplifying your programming tasks. For information about downloading the SDK libraries, go to Sample Code Libraries.

AWS Storage Gateway Required Request Headers

This section describes the required headers that you must send with every POST request to AWS Storage Gateway. You include HTTP headers to identify key information about the request including the operation you want to invoke, the date of the request, and information that indicates the authorization of you as the sender of the request. Headers are case insensitive and the order of the headers is not important.

The following example shows headers that are used in the API_ActivateGateway operation.

POST / HTTP/1.1 
Host: storagegateway.us-east-1.amazonaws.com
Content-Type: application/x-amz-json-1.1
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20120425/us-east-1/storagegateway/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=9cd5a3584d1d67d57e61f120f35102d6b3649066abdd4bf4bbcf05bd9f2f8fe2
x-amz-date: 20120912T120000Z
x-amz-target: StorageGateway_20120630.ActivateGateway

The following are the headers that must include with your POST requests to AWS Storage Gateway. Headers shown below that begin with "x-amz" are AWS-specific headers. All other headers listed are common header used in HTTP transactions.

HeaderDescription
Authorization

The authorization header contains several of pieces of information about the request that enable AWS Storage Gateway to determine if the request is a valid action for the requester. The format of this header is as follows (line breaks added for readability):

Authorization: AWS4-HMAC_SHA456 
Credentials=YourAccessKey/yyymmdd/region/storagegateway/aws4_request, 
SignedHeaders=content-type;host;x-amz-date;x-amz-target, 
Signature=CalculatedSignature

In the preceding syntax, you specify YourAccessKey, the year, month, and day (yyyymmdd), the region, and the CalculatedSignature. The format of the authorization header is dictated by the requirements of the AWS V4 Signing process. The details of signing are discussed in the topic Signing Requests.

Content-Type

Use application/x-amz-json-1.1 as the content type for all requests to AWS Storage Gateway.

Content-Type: application/x-amz-json-1.1

Host

Use the host header to specify the AWS Storage Gateway endpoint where you send your request. For example, storagegateway.us-east-1.amazonaws.com is the endpoint for the US East (N. Virginia) region. For more information about the endpoints available for AWS Storage Gateway, see Regions and Endpoints.

Host: storagegateway.region.amazonaws.com

x-amz-date

You must provide the time stamp in either the HTTP Date header or the AWS x-amz-date header. (Some HTTP client libraries don't let you set the Date header.) When an x-amz-date header is present, the AWS Storage Gateway ignores any Date header during the request authentication. The x-amz-date format must be ISO8601 Basic in the YYYYMMDD'T'HHMMSS'Z' format. If both the Date and x-amz-date header are used, the format of the Date header does not have to be ISO8601.

x-amz-date: YYYYMMDD'T'HHMMSS'Z'

x-amz-target

This header specifies the version of the API and the operation that you are requesting. The target header values are formed by concatenating the API version with the API name and are in the following format.

x-amz-target: StorageGateway_APIversion.operationName

The operationName value (e.g. "ActivateGateway") can be found from the API list, API Reference for AWS Storage Gateway.

Signing Requests

AWS Storage Gateway requires that you authenticate every request you send by signing the request. To sign a request, you calculate a digital signature using a cryptographic hash function. A cryptographic hash is a function that returns a unique hash value based on the input. The input to the hash function includes the text of your request and your secret access key. The hash function returns a hash value that you include in the request as your signature. The signature is part of the Authorization header of your request.

After receiving your request, AWS Storage Gateway recalculates the signature using the same hash function and input that you used to sign the request. If the resulting signature matches the signature in the request, AWS Storage Gateway processes the request. Otherwise, the request is rejected.

AWS Storage Gateway supports authentication using AWS Signature Version 4. The process for calculating a signature can be broken into three tasks:

  • Task 1: Create a Canonical Request

    Rearrange your HTTP request into a canonical format. Using a canonical form is necessary because AWS Storage Gateway uses the same canonical form when it recalculates a signature to compare with the one you sent.

  • Task 2: Create a String to Sign

    Create a string that you will use as one of the input values to your cryptographic hash function. The string, called the string to sign, is a concatenation of the name of the hash algorithm, the request date, a credential scope string, and the canonicalized request from the previous task. The credential scope string itself is a concatenation of date, region, and service information.

  • Task 3: Create a Signature

    Create a signature for your request by using a cryptographic hash function that accepts two input strings: your string to sign and a derived key. The derived key is calculated by starting with your secret access key and using the credential scope string to create a series of Hash-based Message Authentication Codes (HMACs).

Example Signature Calculation

The following example walks you through the details of creating a signature for API_ListGateways. The example could be used as a reference to check your signature calculation method. Other reference calculations are included in the Signature Version 4 Test Suite of the Amazon Web Services Glossary.

The example assumes the following:

  • The time stamp of the request is "Mon, 10 Sep 2012 00:00:00" GMT.

  • The endpoint is the US East (N. Virginia) region.

The general request syntax (including the JSON body) is:

POST / HTTP/1.1
Host: storagegateway.us-east-1.amazonaws.com
x-amz-Date: 20120910T000000Z
Authorization: SignatureToBeCalculated
Content-type: application/x-amz-json-1.1
x-amz-target: StorageGateway_20120630.ListGateways
{}

The canonical form of the request calculated for Task 1: Create a Canonical Request is:

POST
/

content-type:application/x-amz-json-1.1
host:storagegateway.us-east-1.amazonaws.com
x-amz-date:20120910T000000Z
x-amz-target:StorageGateway_20120630.ListGateways

content-type;host;x-amz-date;x-amz-target
44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a

The last line of the canonical request is the hash of the request body. Also, note the empty third line in the canonical request. This is because there are no query parameters for this API (or any AWS Storage Gateway APIs).

The string to sign for Task 2: Create a String to Sign is:

AWS4-HMAC-SHA256
20120910T000000Z
20120910/us-east-1/storagegateway/aws4_request
92c0effa6f9224ac752ca179a04cecbede3038b0959666a8160ab452c9e51b3e

The first line of the string to sign is the algorithm, the second line is the time stamp, the third line is the credential scope, and the last line is a hash of the canonical request from Task 1.

For Task 3: Create a Signature, the derived key can be represented as:

derived key = HMAC(HMAC(HMAC(HMAC("AWS4" + YourSecretAccessKey,"20120910"),"us-east-1"),"storagegateway"),"aws4_request")

If the secret access key, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY, is used, then the calculated signature is:

6d4c40b8f2257534dbdca9f326f147a0a7a419b63aff349d9d9c737c9a0f4c81

The final step is to construct the Authorization header. For the demonstration access key AKIAIOSFODNN7EXAMPLE, the header (with line breaks added for readability) is:

Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20120910/us-east-1/storagegateway/aws4_request, 
SignedHeaders=content-type;host;x-amz-date;x-amz-target, 
Signature=6d4c40b8f2257534dbdca9f326f147a0a7a419b63aff349d9d9c737c9a0f4c81

Error Responses

This section provides reference information about AWS Storage Gateway errors. These errors are represented by an error exception and an operation error code. For example, the error exception InvalidSignatureException is returned by any API response if there is a problem with the request signature. However, the operation error code ActivationKeyInvalid is returned only for the ActivateGateway API.

Depending on the type of error, AWS Storage Gateway may return only just an exception, or it may return both an exception and an operation error code. Examples of error responses are shown in the Error Responses.

Exceptions

The following table lists AWS Storage Gateway API exceptions. When an AWS Storage Gateway operation returns an error response, the response body contains one of these exceptions. The InternalServerError and InvalidGatewayRequestException return one of the operation error codes Operation Error Codes message codes that give the specific operation error code.

ExceptionMessage HTTP Status Code
IncompleteSignatureExceptionThe specified signature is incomplete.400 Bad Request
InternalFailureThe request processing has failed due to some unknown error, exception or failure. 500 Internal Server Error
InternalServerErrorOne of the operation error code messages Operation Error Codes.500 Internal Server Error
InvalidActionThe requested action or operation is invalid.400 Bad Request
InvalidClientTokenIdThe X.509 certificate or AWS Access Key ID provided does not exist in our records. 403 Forbidden
InvalidGatewayRequestExceptionOne of the operation error code messages in Operation Error Codes.400 Bad Request
InvalidSignatureExceptionThe request signature we calculated does not match the signature you provided. Check your AWS Access Key and signing method.400 Bad Request
MissingActionThe request is missing an action or operation parameter. 400 Bad Request
MissingAuthenticationTokenThe request must contain either a valid (registered) AWS Access Key ID or X.509 certificate. 403 Forbidden
RequestExpiredThe request is past the expiration date or the request date (either with 15 minute padding), or the request date occurs more than 15 minutes in the future. 400 Bad Request
SerializationExceptionAn error occurred during serialization. Check that your JSON payload is well-formed.400 Bad Request
ServiceUnavailableThe request has failed due to a temporary failure of the server. 503 Service Unavailable
SubscriptionRequiredExceptionThe AWS Access Key Id needs a subscription for the service.400 Bad Request
ThrottlingExceptionRate exceeded.400 Bad Request
UnknownOperationExceptionAn unknown operation was specified. Valid operations are listed in Operations in AWS Storage Gateway.400 Bad Request
UnrecognizedClientExceptionThe security token included in the request is invalid.400 Bad Request
ValidationExceptionThe value of an input parameter is bad or out of range.400 Bad Request

Operation Error Codes

The following table shows the mapping between AWS Storage Gateway operation error codes and APIs that can return the codes. All operation error codes are returned with one of two general exceptions—InternalServerError and InvalidGatewayRequestException—described in Exceptions.

Operation Error CodeMessageOperations That Return this Error Code
ActivationKeyExpiredThe specified activation key has expired.ActivateGateway
ActivationKeyInvalidThe specified activation key is invalid.ActivateGateway
ActivationKeyNotFoundThe specified activation key was not found.ActivateGateway
BandwidthThrottleScheduleNotFoundThe specified bandwidth throttle was not found.DeleteBandwidthRateLimit
CannotExportSnapshotThe specified snapshot cannot be exported.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

InitiatorNotFoundThe specified initiator was not found.DeleteChapCredentials
DiskAlreadyAllocatedThe specified disk is already allocated.

AddCache

AddUploadBuffer

AddWorkingStorage

CreateStorediSCSIVolume

DiskDoesNotExistThe specified disk does not exist.

AddCache

AddUploadBuffer

AddWorkingStorage

CreateStorediSCSIVolume

DiskSizeNotGigAlignedThe specified disk is not gigabyte-aligned.

CreateStorediSCSIVolume

DiskSizeGreaterThanVolumeMaxSizeThe specified disk size is greater than the maximum volume size.CreateStorediSCSIVolume
DiskSizeLessThanVolumeSizeThe specified disk size is less than the volume size.CreateStorediSCSIVolume
DuplicateCertificateInfoThe specified certificate information is a duplicate.ActivateGateway
GatewayInternalErrorA gateway internal error occurred.

AddCache

AddUploadBuffer

AddWorkingStorage

CreateCachediSCSIVolume

CreateSnapshot

CreateStorediSCSIVolume

CreateSnapshotFromVolumeRecoveryPoint

DeleteBandwidthRateLimit

DeleteChapCredentials

DeleteVolume

DescribeBandwidthRateLimit

DescribeCache

DescribeCachediSCSIVolumes

DescribeChapCredentials

DescribeGatewayInformation

DescribeMaintenanceStartTime

DescribeSnapshotSchedule

DescribeStorediSCSIVolumes

DescribeWorkingStorage

ListLocalDisks

ListVolumes

ListVolumeRecoveryPoints

ShutdownGateway

StartGateway

UpdateBandwidthRateLimit

UpdateChapCredentials

UpdateMaintenanceStartTime

UpdateGatewaySoftwareNow

UpdateSnapshotSchedule

GatewayNotConnectedThe specified gateway is not connected.

AddCache

AddUploadBuffer

AddWorkingStorage

CreateCachediSCSIVolume

CreateSnapshot

CreateStorediSCSIVolume

CreateSnapshotFromVolumeRecoveryPoint

DeleteBandwidthRateLimit

DeleteChapCredentials

DeleteVolume

DescribeBandwidthRateLimit

DescribeCache

DescribeCachediSCSIVolumes

DescribeChapCredentials

DescribeGatewayInformation

DescribeMaintenanceStartTime

DescribeSnapshotSchedule

DescribeStorediSCSIVolumes

DescribeWorkingStorage

ListLocalDisks

ListVolumes

ListVolumeRecoveryPoints

ShutdownGateway

StartGateway

UpdateBandwidthRateLimit

UpdateChapCredentials

UpdateMaintenanceStartTime

UpdateGatewaySoftwareNow

UpdateSnapshotSchedule

GatewayNotFoundThe specified gateway was not found.

AddCache

AddUploadBuffer

AddWorkingStorage

CreateCachediSCSIVolume

CreateSnapshot

CreateSnapshotFromVolumeRecoveryPoint

CreateStorediSCSIVolume

DeleteBandwidthRateLimit

DeleteChapCredentials

DeleteGateway

DeleteVolume

DescribeBandwidthRateLimit

DescribeCache

DescribeCachediSCSIVolumes

DescribeChapCredentials

DescribeGatewayInformation

DescribeMaintenanceStartTime

DescribeSnapshotSchedule

DescribeStorediSCSIVolumes

DescribeWorkingStorage

ListLocalDisks

ListVolumes

ListVolumeRecoveryPoints

ShutdownGateway

StartGateway

UpdateBandwidthRateLimit

UpdateChapCredentials

UpdateMaintenanceStartTime

UpdateGatewaySoftwareNow

UpdateSnapshotSchedule

GatewayProxyNetworkConnectionBusyThe specified gateway proxy network connection is busy.

AddCache

AddUploadBuffer

AddWorkingStorage

CreateCachediSCSIVolume

CreateSnapshot

CreateSnapshotFromVolumeRecoveryPoint

CreateStorediSCSIVolume

DeleteBandwidthRateLimit

DeleteChapCredentials

DeleteVolume

DescribeBandwidthRateLimit

DescribeCache

DescribeCachediSCSIVolumes

DescribeChapCredentials

DescribeGatewayInformation

DescribeMaintenanceStartTime

DescribeSnapshotSchedule

DescribeStorediSCSIVolumes

DescribeWorkingStorage

ListLocalDisks

ListVolumes

ListVolumeRecoveryPoints

ShutdownGateway

StartGateway

UpdateBandwidthRateLimit

UpdateChapCredentials

UpdateMaintenanceStartTime

UpdateGatewaySoftwareNow

UpdateSnapshotSchedule

InternalErrorAn internal error occurred.

ActivateGateway

AddCache

AddUploadBuffer

AddWorkingStorage

CreateCachediSCSIVolume

CreateSnapshot

CreateSnapshotFromVolumeRecoveryPoint

CreateStorediSCSIVolume

DeleteBandwidthRateLimit

DeleteChapCredentials

DeleteGateway

DeleteVolume

DescribeBandwidthRateLimit

DescribeCache

DescribeCachediSCSIVolumes

DescribeChapCredentials

DescribeGatewayInformation

DescribeMaintenanceStartTime

DescribeSnapshotSchedule

DescribeStorediSCSIVolumes

DescribeWorkingStorage

ListLocalDisks

ListGateways

ListVolumes

ListVolumeRecoveryPoints

ShutdownGateway

StartGateway

UpdateBandwidthRateLimit

UpdateChapCredentials

UpdateMaintenanceStartTime

UpdateGatewayInformation

UpdateGatewaySoftwareNow

UpdateSnapshotSchedule

InvalidParametersThe specified request contains invalid parameters.

ActivateGateway

AddCache

AddUploadBuffer

AddWorkingStorage

CreateCachediSCSIVolume

CreateSnapshot

CreateSnapshotFromVolumeRecoveryPoint

CreateStorediSCSIVolume

DeleteBandwidthRateLimit

DeleteChapCredentials

DeleteGateway

DeleteVolume

DescribeBandwidthRateLimit

DescribeCache

DescribeCachediSCSIVolumes

DescribeChapCredentials

DescribeGatewayInformation

DescribeMaintenanceStartTime

DescribeSnapshotSchedule

DescribeStorediSCSIVolumes

DescribeWorkingStorage

ListLocalDisks

ListGateways

ListVolumes

ListVolumeRecoveryPoints

ShutdownGateway

StartGateway

UpdateBandwidthRateLimit

UpdateChapCredentials

UpdateMaintenanceStartTime

UpdateGatewayInformation

UpdateGatewaySoftwareNow

UpdateSnapshotSchedule

LocalStorageLimitExceededThe local storage limit was exceeded.

AddCache

AddUploadBuffer

AddWorkingStorage

LunInvalidThe specified LUN is invalid.CreateStorediSCSIVolume
MaximumVolumeCountExceededThe maximum volume count was exceeded.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

DescribeCachediSCSIVolumes

DescribeStorediSCSIVolumes

NetworkConfigurationChangedThe gateway network configuration has changed.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

NotSupportedThe specified operation is not supported.

ActivateGateway

AddCache

AddUploadBuffer

AddWorkingStorage

CreateCachediSCSIVolume

CreateSnapshot

CreateSnapshotFromVolumeRecoveryPoint

CreateStorediSCSIVolume

DeleteBandwidthRateLimit

DeleteChapCredentials

DeleteGateway

DeleteVolume

DescribeBandwidthRateLimit

DescribeCache

DescribeCachediSCSIVolumes

DescribeChapCredentials

DescribeGatewayInformation

DescribeMaintenanceStartTime

DescribeSnapshotSchedule

DescribeStorediSCSIVolumes

DescribeWorkingStorage

ListLocalDisks

ListGateways

ListVolumes

ListVolumeRecoveryPoints

ShutdownGateway

StartGateway

UpdateBandwidthRateLimit

UpdateChapCredentials

UpdateMaintenanceStartTime

UpdateGatewayInformation

UpdateGatewaySoftwareNow

UpdateSnapshotSchedule

OutdatedGatewayThe specified gateway is out of date.ActivateGateway
SnapshotInProgressExceptionThe specified snapshot is in progress.DeleteVolume
SnapshotIdInvalidThe specified snapshot is invalid.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

StagingAreaFullThe staging area is full.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

TargetAlreadyExistsThe specified target already exists.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

TargetInvalidThe specified target is invalid.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

DeleteChapCredentials

DescribeChapCredentials

UpdateChapCredentials

TargetNotFoundThe specified target was not found.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

DeleteChapCredentials

DescribeChapCredentials

DeleteVolume

UpdateChapCredentials

UnsupportedOperationForGatewayTypeThe specified operation is not valid for the type of the gateway.

AddCache

AddWorkingStorage

CreateCachediSCSIVolume

CreateSnapshotFromVolumeRecoveryPoint

CreateStorediSCSIVolume

DeleteSnapshotSchedule

DescribeCache

DescribeCachediSCSIVolumes

DescribeStorediSCSIVolumes

DescribeUploadBuffer

DescribeWorkingStorage

ListVolumeRecoveryPoints

VolumeAlreadyExistsThe specified volume already exists.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

VolumeIdInvalidThe specified volume is invalid.DeleteVolume
VolumeInUseThe specified volume is already in use.DeleteVolume
VolumeNotFoundThe specified volume was not found.

CreateSnapshot

CreateSnapshotFromVolumeRecoveryPoint

DeleteVolume

DescribeCachediSCSIVolumes

DescribeSnapshotSchedule

DescribeStorediSCSIVolumes

UpdateSnapshotSchedule

VolumeNotReadyThe specified volume is not ready.

CreateSnapshot

CreateSnapshotFromVolumeRecoveryPoint

Error Responses

When there is an error, the response header information contains:

  • Content-Type: application/x-amz-json-1.1

  • An appropriate 4xx or 5xx HTTP status code

The body of an error response contains information about the error that occurred. The following sample error response shows the output syntax of response elements common to all error responses.

{
    "__type": "String",
    "message": "String",
    "error":
        { "errorCode": "String",
          "errorDetails": "String"
        }
}

The following table explains the JSON error response fields shown in the preceding syntax.

__type

One of the exceptions from Exceptions.

Type: String

error

Contains API-specific error details. In general errors (i.e., not specific to any API), this error information is not shown.

Type: Collection

errorCode

One of the operation error codes .

Type: String

errorDetails

This field is not used in the current version of the API.

Type: String

message

One of the operation error code messages.

Type: String

Error Response Examples

The following JSON body is returned if you use the DescribeStorediSCSIVolumes API and specify a gateway ARN request input that does not exist.

{
  "__type": "InvalidGatewayRequestException",
  "message": "The specified volume was not found.",
  "error": {
    "errorCode": "VolumeNotFound"
  }
}

The following JSON body is returned if AWS Storage Gateway calculates a signature that does not match the signature sent with a request.

{  
  "__type": "InvalidSignatureException",  
  "message": "The request signature we calculated does not match the signature you provided." 
}  

Operations in AWS Storage Gateway

For a list of AWS Storage Gateway operations, go to Actions in the AWS Storage Gateway API Reference.