REST API Introduction
- 02 Feb 2023
- Print
- PDF
REST API Introduction
- Updated on 02 Feb 2023
- Print
- PDF
Article Summary
Share feedback
Thanks for sharing your feedback!
Host Designation
Wasabi supports both the path-style and virtual-style requests available with AWS S3. A different host name is required (for example, s3.wasabisys.com versus s3.amazonaws.com). Wasabi recommends using path-style requests as shown in all examples in this guide (for example, http://s3.wasabisys.com/my-bucket/my-object) because the path-style offers the greatest flexibility in bucket names, avoiding domain name issues.
Error Responses
Where possible, Wasabi utilizes the exact error responses given by AWS S3. Some additional error codes are provided for additional functionality in Wasabi.
HTTP Error Codes
| Error Code | Wasabi Description | HTTP Status Code |
|---|---|---|
| Unavailable | Temporarily unavailable | 503 |
| Unrecoverable | DataUnrecoverable | |
| NotImplemented | Not Implemented | 501 |
| DBEntityNotfound | No such entity | 404 |
| DBEntityFound | EntityAlreadyExists | 409 |
| DisconnectError | ConnectionClosed | 410 |
| StatusInternalServerError | InternalError, We encountered an internal error. Please contact customer support. | 500 |
| StatusForbidden | AccessDenied | 403 |
| AccessForbidden | ||
| AccountNotActivated | ||
| AccountProblem | ||
| AuthenticationLockout, There have been too many attempts to access the account with the wrong credentials. Please try again in five minutes. | ||
| InvalidAccessKeyId, The AWS Access Key Id you provided does not exist in our records. | ||
| InvalidAuthenticationCode, Authentication code for device is not valid. | ||
| RequestTimeTooSkewed, The difference between the request time and the current time is too large. | ||
| InvalidObjectState, The operation is not valid for the current state of the object. | ||
| StatusBadRequest | AuthorizationHeaderMalformed | 400 |
| AuthorizationQueryParametersError | ||
| BadDigest, The Content-MD5 you specified did not match what we received. | ||
| BadRequest, An error occurred when parsing the HTTP request. | ||
| IncompleteSignature, Request must contain a signature that conforms to AWS standards. | ||
| InvalidAction | ||
| InvalidArgument | ||
| InvalidDigest, The Content-MD5 you specified was invalid. | ||
| InvalidInput | ||
| InvalidParameterValue, An invalid or out-of-range value was supplied for the input parameter. | ||
| InvalidRequest | ||
| MalformedPolicy | ||
| MalformedPolicyDocument | ||
| PasswordPolicyViolation | ||
| ValidationError | ||
| XAmzContentSHA256Mismatch, The provided 'x-amz-content-sha256' header does not match what was computed. | ||
| EncryptionNotAllowed, User provided encryption keys are not allowed in this operation. | ||
| The object was stored using a form of Server Side Encryption. The correct parameters must be provided to retrieve the object. | ||
| EntityTooLarge, Your proposed upload is larger than the maximum allowed size. | ||
| EntityTooSmall, Your proposed upload is smaller than the minimum allowed size. | ||
| IllegalComplianceRequest | ||
| IllegalVersioningConfigurationException, The versioning configuration specified in the request is not valid. | ||
| IncompleteBody, You did not provide the number of bytes specified by the Content-Length HTTP header. | ||
| InvalidACLRequest, You must provide only one of either ACL headers or an XML body when setting ACLs. | ||
| InvalidArgument | ||
| InvalidBucketName, The specified bucket is not valid. | ||
| InvalidEncryptionAlgorithmError, The Encryption request you specified is not valid. Supported value: AES256. | ||
| InvalidPartOrder, The list of parts was not in ascending order. Parts must be ordered by part number. | ||
| InvalidPart, One or more of the specified parts could not be found. The part may not have been uploaded, or the specified entity tag may not match the part's entity tag. | ||
| InvalidPolicyDocument, The content of the form does not meet the conditions specified in the policy document. | ||
| KeyTooLongError, Your key is too long. | ||
| LoggingBucketSameOwner, The logging target bucket must have the same owner as the bucket being logged. | ||
| MalformedXML, The XML you provided was not well formed or did not validate against our published schema. | ||
| MetadataTooLarge, Your metadata headers exceed the maximum allowed metadata size. | ||
| RequestTimeout, Your socket connection to the server was not read from or written to within the timeout period. | ||
| TooManyBuckets, You have attempted to create more buckets than allowed. | ||
| TooManyComponents, A composite object may not have more than 1024 components. | ||
| UnresolvableGrantByEmailAddress, The email address you provided does not match any account on record. | ||
| StorageQuotaExceeded, Your account has surpassed it's storage limit. | ||
| BucketAccountInactive, The account that owns this bucket is not active. | ||
| StatusGone | ConnectionClosed, Network connection was closed. | 410 |
| StatusUnprocessableEntity | DataUnrecoverable, The data in the request is unrecoverable. Please contact customer support. | 422 |
| StatusConflict | DeleteConflict | 409 |
| EntityAlreadyExists | ||
| EntityTemporarilyUnmodifiable, The entity is temporarily unmodifiable. Please try again later. | ||
| Limit Exceeded | ||
| OperationAborted, A conflicting conditional operation is currently in progress against this resource. Please try again. | ||
| BucketAlreadyExists | ||
| BucketNotEmpty | ||
| ComplianceSettingsLocked, The compliance settings are now locked and cannot be changed. | ||
| StatusNotFound | NoSuchEntity | 404 |
| NoSuchLifecycleConfiguration, The lifecycle configuration does not exist. | ||
| NoSuchBucket, The specified bucket does not exist. | ||
| NoSuchBucketPolicy, The bucket policy does not exist. | ||
| NoSuchKey, The specified key does not exist. | ||
| NoSuchReplicationConfiguration, The replication configuration does not exist. | ||
| NoSuchTagSetError, There is no tag set associated with the bucket. | ||
| NoSuchUpload, The specified upload does not exist. The upload ID may be invalid, or the upload may have been aborted or completed. | ||
| NoSuchVersion, The specified version does not exist. | ||
| StatusNotImplemented | NotImplemented, A header you provided implies functionality that is not implemented. | 501 |
| StatusServiceUnavailable | TemporarilyUnavailable, Resources for this operation are temporarily unavailable. Please try again later. | 503 |
| StatusFound | KeyAlreadyExists | 302 |
| StatusMethodNotAllowed | MethodNotAllowed, This method is not allowed for other than the account owner. | 405 |
| MethodNotAllowed, The specified method is not allowed against this resource. | ||
| StatusLengthRequired | MissingContentLength, You must provide the Content-Length HTTP header. | 411 |
TCP Error Codes
Wasabi also supports the following TCP error codes:
- Unexpected EOF
- Broken Pipe
- Connection reset by Peer
“Always Consistent” Feature
Rather than providing “always consistent” operations, AWS S3 operations are “strong consistency.” When you perform an AWS S3 operation, the results that follow may not reflect the previous operation.
Wasabi provides an “always consistent” view of all operations. Any operation following another will have the same expected result. This eliminates the special programming needed to wait for completion of a prior operation. As an example, after a DELETE on an object, it is common to perform a HEAD operation to check that the deletion was successful. Wasabi will always return a successful HEAD after the DELETE operation.
Authenticating Requests
Wasabi supports autonomous and signature versions 2 and 4 compatible with AWS S3, for both headers and query parameters. Generally, the signature version 4 offers better security, but requires more compute time on both the client and server because of the overhead calculating the SHA256 hash. If performance time is critical to your application, use the version 2 signing and check the calculated MD5 (returned as the ETag header for an object) for data integrity.
For version 4 signing requests, all regions are supported for Wasabi signing requests (“us-east-1” is the default AWS S3 region).
Wasabi does not support signature signing for browser based uploads and HTML form requests because this is used for web page operations. (Web page operations are not currently supported on Wasabi).
For signature version 2, Wasabi added subresource keys that are specified as query parameters on the request. The specific subresource keys are:
- append
- compose
- force_delete=true
which are query parameters given for the PutObject and DeleteBucket operations. When using signature version 2, you need to include these in the calculation of the signing.
Not Supported in Wasabi
| Operation | Description |
|---|---|
| SOAP | AWS S3 has deprecated support for SOAP. As a result, Wasabi does not support any SOAP operations. |
