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, see 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 ActivateGateway operation.

Copy
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.

Header Description
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):

Copy
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.

Copy
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.

Copy
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.

Copy
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.

Copy
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 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:

Copy
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 is:

Copy
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 is:

Copy
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 , the derived key can be represented as:

Copy
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:

Copy
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:

Copy
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.

Exception Message HTTP Status Code
IncompleteSignatureException The specified signature is incomplete. 400 Bad Request
InternalFailure The request processing has failed due to some unknown error, exception or failure. 500 Internal Server Error
InternalServerError One of the operation error code messages Operation Error Codes. 500 Internal Server Error
InvalidAction The requested action or operation is invalid. 400 Bad Request
InvalidClientTokenId The X.509 certificate or AWS Access Key ID provided does not exist in our records. 403 Forbidden
InvalidGatewayRequestException One of the operation error code messages in Operation Error Codes. 400 Bad Request
InvalidSignatureException The request signature we calculated does not match the signature you provided. Check your AWS Access Key and signing method. 400 Bad Request
MissingAction The request is missing an action or operation parameter. 400 Bad Request
MissingAuthenticationToken The request must contain either a valid (registered) AWS Access Key ID or X.509 certificate. 403 Forbidden
RequestExpired The 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
SerializationException An error occurred during serialization. Check that your JSON payload is well-formed. 400 Bad Request
ServiceUnavailable The request has failed due to a temporary failure of the server. 503 Service Unavailable
SubscriptionRequiredException The AWS Access Key Id needs a subscription for the service. 400 Bad Request
ThrottlingException Rate exceeded. 400 Bad Request
UnknownOperationException An unknown operation was specified. Valid operations are listed in Operations in AWS Storage Gateway. 400 Bad Request
UnrecognizedClientException The security token included in the request is invalid. 400 Bad Request
ValidationException The 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 Code Message Operations That Return this Error Code
ActivationKeyExpired The specified activation key has expired. ActivateGateway
ActivationKeyInvalid The specified activation key is invalid. ActivateGateway
ActivationKeyNotFound The specified activation key was not found. ActivateGateway
BandwidthThrottleScheduleNotFound The specified bandwidth throttle was not found. DeleteBandwidthRateLimit
CannotExportSnapshot The specified snapshot cannot be exported.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

InitiatorNotFound The specified initiator was not found. DeleteChapCredentials
DiskAlreadyAllocated The specified disk is already allocated.

AddCache

AddUploadBuffer

AddWorkingStorage

CreateStorediSCSIVolume

DiskDoesNotExist The specified disk does not exist.

AddCache

AddUploadBuffer

AddWorkingStorage

CreateStorediSCSIVolume

DiskSizeNotGigAligned The specified disk is not gigabyte-aligned.

CreateStorediSCSIVolume

DiskSizeGreaterThanVolumeMaxSize The specified disk size is greater than the maximum volume size. CreateStorediSCSIVolume
DiskSizeLessThanVolumeSize The specified disk size is less than the volume size. CreateStorediSCSIVolume
DuplicateCertificateInfo The specified certificate information is a duplicate. ActivateGateway
GatewayInternalError A 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

GatewayNotConnected The 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

GatewayNotFound The 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

GatewayProxyNetworkConnectionBusy The 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

InternalError An 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

InvalidParameters The 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

LocalStorageLimitExceeded The local storage limit was exceeded.

AddCache

AddUploadBuffer

AddWorkingStorage

LunInvalid The specified LUN is invalid. CreateStorediSCSIVolume
MaximumVolumeCountExceeded The maximum volume count was exceeded.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

DescribeCachediSCSIVolumes

DescribeStorediSCSIVolumes

NetworkConfigurationChanged The gateway network configuration has changed.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

NotSupported The 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

OutdatedGateway The specified gateway is out of date. ActivateGateway
SnapshotInProgressException The specified snapshot is in progress. DeleteVolume
SnapshotIdInvalid The specified snapshot is invalid.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

StagingAreaFull The staging area is full.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

TargetAlreadyExists The specified target already exists.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

TargetInvalid The specified target is invalid.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

DeleteChapCredentials

DescribeChapCredentials

UpdateChapCredentials

TargetNotFound The specified target was not found.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

DeleteChapCredentials

DescribeChapCredentials

DeleteVolume

UpdateChapCredentials

UnsupportedOperationForGatewayType The specified operation is not valid for the type of the gateway.

AddCache

AddWorkingStorage

CreateCachediSCSIVolume

CreateSnapshotFromVolumeRecoveryPoint

CreateStorediSCSIVolume

DeleteSnapshotSchedule

DescribeCache

DescribeCachediSCSIVolumes

DescribeStorediSCSIVolumes

DescribeUploadBuffer

DescribeWorkingStorage

ListVolumeRecoveryPoints

VolumeAlreadyExists The specified volume already exists.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

VolumeIdInvalid The specified volume is invalid. DeleteVolume
VolumeInUse The specified volume is already in use. DeleteVolume
VolumeNotFound The specified volume was not found.

CreateSnapshot

CreateSnapshotFromVolumeRecoveryPoint

DeleteVolume

DescribeCachediSCSIVolumes

DescribeSnapshotSchedule

DescribeStorediSCSIVolumes

UpdateSnapshotSchedule

VolumeNotReady The 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.

Copy
{ "__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.

Copy
{ "__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.

Copy
{   "__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, see Actions in the AWS Storage Gateway API Reference.