REST API Introduction
    • 02 Feb 2023
    • 4 Minutes to read
    • PDF

    REST API Introduction

    • PDF

    Article summary

    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 CodeWasabi DescriptionHTTP Status Code
    UnavailableTemporarily unavailable503
    UnrecoverableDataUnrecoverable
    NotImplementedNot Implemented501
    DBEntityNotfoundNo such entity404
    DBEntityFoundEntityAlreadyExists409
    DisconnectErrorConnectionClosed410
    StatusInternalServerErrorInternalError, We encountered an internal error. Please contact customer support.500
    StatusForbiddenAccessDenied403
    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.
    StatusBadRequestAuthorizationHeaderMalformed400
    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.
    StatusGoneConnectionClosed, Network connection was closed.410
    StatusUnprocessableEntityDataUnrecoverable, The data in the request is unrecoverable. Please contact customer support.422
    StatusConflictDeleteConflict409
    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.
    StatusNotFoundNoSuchEntity404
    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.
    StatusNotImplementedNotImplemented, A header you provided implies functionality that is not implemented.501
    StatusServiceUnavailableTemporarilyUnavailable, Resources for this operation are temporarily unavailable. Please try again later.503
    StatusFoundKeyAlreadyExists302
    StatusMethodNotAllowedMethodNotAllowed, This method is not allowed for other than the account owner.405
    MethodNotAllowed, The specified method is not allowed against this resource.
    StatusLengthRequiredMissingContentLength, 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

    OperationDescription
    SOAPAWS S3 has deprecated support for SOAP. As a result, Wasabi does not support any SOAP operations.