Requests and responses

The request line for an S3 compatible request specifies the operation to be performed and the version of HTTP on which the S3 compatible API is based. Additionally:

• If the target of the request is a tenant or if the target is a bucket and the hostname includes the bucket name, the request line includes a forward slash by itself.

  For example, here are the request line and HOST header for a request to create a bucket named finance where the bucket name is included in the hostname:

  PUT / HTTP/1.1
  HOST: finance.europe.hcp.example.com

• If the target of the request is a bucket and the hostname does not include the bucket name, the request line includes the a forward slash followed by the bucket name.

  For example, here are the request line and HOST header for a request to create a bucket named finance where the bucket name is not included in the hostname:

  PUT /finance HTTP/1.1
  HOST: europe.hcp.example.com

• If the target of the operation is an object, the request line includes a forward slash followed by the object name either by itself or following the bucket name, depending on whether the hostnames includes the bucket name.

  For example, here are the request line and HOST header for a request to create an object named quarterly_rpts/Q4_2019 where the bucket name is included in the hostname:

  PUT /quarterly_rpts/Q4_2019 HTTP/1.1
  HOST: finance.europe.hcp.example.com

  Here are the request line and HOST header for a request to create an object named quarterly_rpts/Q4_2019 in a bucket named finance where the bucket name is not included in the hostname:

  PUT /finance/quarterly_rpts/Q4_2019 HTTP/1.1
  HOST: europe.hcp.example.com

• If the request uses any query parameters, those parameters are appended to the last one of the items listed above.

  For example, here are the request line and HOST header for a request to add an ACL to an object named quarterly_rpts/Q4_2019 where the bucket name is included in the hostname:

  PUT /quarterly_rpts/Q4_2019?acl HTTP/1.1
  HOST: finance.europe.hcp.example.com

  If the request includes invalid query parameters, those parameters are ignored.

Some request headers are common to all S3 compatible API requests. The list below describes those headers. Request headers that are specific to certain requests are described in the sections for those requests.

Request header names are not case sensitive. Depending on the header, the header values may be case sensitive.

• Authorization

  Specifies user credentials or requests anonymous access.

• Date

  Specifies the date and time when the request is being made according to the requester. Normally, this is the current date and time.

  The date and time must always be specified using Greenwich Mean Time (GMT).

  To specify the date and time, use this format:

  DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)

  In this format:

  • DDD

    The three-letter abbreviation for the day of the week, with an uppercase first letter (for example, Mon).

  • dd

    The two-digit day of the month.

  • MMM

    The three-letter abbreviation for the month, with an uppercase first letter (for example, Feb).

  • yyyy

    The four-digit year.

  • HH

    The hour on a 24-hour clock.

  • mm

    The number of minutes.

  • ss

    The number of seconds.

  For example:

  Thu, 23 Mar 2017 14:27:05 +0000

  All S3 compatible requests must include either a Date header or an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-amz-date header.

• Host

  Specifies the hostname for the request. The host name identifies either a tenant or a bucket.

  For a tenant, use this format:

  tenant-name.hcp-domain-name

  For a bucket, use this format:

  bucket-name.tenant-name.hcp-domain-name

• x-amz-date

  Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.

  For the valid values for this header, see the description of the Date header above.

• x-amz-acl

  Adds a canned ACL to the bucket.

  This header is used only to add a canned ACL to a bucket. If you’re using individual x-amz-grant- headers to add the ACL, the x-amz-acl header is invalid.

• x-amz-grant-full-control

  Grants full control over the bucket to one or more specified grantees.

  If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-full-control header is invalid.

• x-amz-grant-read

  Grants the browse and read data access permissions for the bucket to one or more specified grantees.

  If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-read header is invalid.

• x-amz-grant-read-acp

  Grants the read ACL data access permission for the bucket to one or more specified grantees.

  If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-read-acp header is invalid.

• x-amz-grant-write

  Grants the write and delete data access permissions for the bucket to one or more specified grantees.

  If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-write header is invalid.

• x-amz-grant-write-acp

  Grants the write ACL data access permission for the bucket to one or more specified grantees.

  If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-write-acp header is invalid.

• x-hcp-pretty-print

  Optionally, requests that the XML response body be formatted for readability. Valid values are:

  • true

    Format the XML response body for readability.

  • false

    Do not apply any special formatting to the XML response body.

  The default is false.

  The values true and false are not case sensitive.

The status line returned in response to an S3 compatible request specifies the version of HTTP on which the S3 compatible API is based and an HTTP status code that indicates the outcome of the request. HTTP status codes in the 2xx range indicate that the requested operation was successful. HTTP status codes in the 3xx, 4xx, and 5xx ranges, typically indicate that an error occurred and HCP did not perform the requested operation.

Here’s an example of a response status line that indicates that the requested operation was successful:

HTTP/1.1 200 OK

Some response headers are common to all S3 compatible API requests, while some are specific to certain requests. The table below describes some of the common response headers.

• Content-Length

  The size, in bytes, of the response body if HCP can determine the size before formulating the response.

  If the response does not include a response body, the value of the Content-Length header is 0 (zero).

• Content-Type

  The Internet media type of the response body if HCP can determine the Internet media type. If HCP cannot determine the Internet media type, the value of this header is application/octet-stream.

  Because HCP returns error information in a response body, the response to any request can include a Content-Type header.

• Date

  The date and time when HCP responded to the request, in Greenwich Mean Time (GMT). The date and time are returned in this format:

  DDD dd MMM yyyy HH:mm:ss GMT

  For example:

  Fri, 18 Sep 2020 14:27:05 GMT

• Transfer-Encoding

  Always chunked. This header is returned if the response includes a response body but HCP cannot determine the size of the response body before formulating the response.

  Because HCP returns error information in a response body, the response to any request can include a Transfer-Encoding header.

Some common response headers address browser security concerns. These headers have fixed values. The table below describes these headers.

• Cache-Control

  Specifies directives that must be obeyed by all caching mechanisms along the request/response chain

  Values: no-cache, no-store, must-revalidate

• Content-Security-Policy

  Restricts the content that the browser can load to the sources specified by the header value

  Values: default-src 'self'; script-src 'self' 'unsafe-eval' 'unsafe-inline'; connect-src 'self'; img-src 'self'; style-src 'self' 'unsafe-inline'; object-src 'self'; frame-ancestors 'self';

• Expires

  Causes the response to become stale immediately after it is sent

  Value: Thu, 01 Jan 1970 00:00:00 GMT

• Pragma

  Prevents the response from being used for subsequent requests for the same resource without the browser first checking whether the resource has changed

  Value: no-cache

• X-Content-Type-Options

  Prevents the browser from examining the returned content to determine the content MIME type

  Value: nosniff

• X-DNS-Prefetch-Control

  Prevents the browser from performing domain name resolution on URLs embedded in returned content before the URLs are requested

  Value: off

• X-Download-Options

  Prevents the browser from opening resources that are downloaded through links in the returned content

  Value: noopen

• X-Frame-Options

  Prevents the browser from rendering the returned content in a frame on a page containing content not returned by the HCP system

• X-XSS-Protection

  Stops the browser from loading the returned content if the browser detects reflected cross-site scripting (XSS) in the response

  Values: 1; mode=block

For information about request-specific response headers, see the "Response header" topic for each type of operation you can perform with the S3 compatible API.

When an S3 compatible request results in an error, HCP returns information about the error in an error request body. An error request body contains XML in this format:

<?xml version="1.0" encoding="UTF-8"?>
<Error>
     <Code>error-code</Code>
     <Message>error-message</Message>
     <RequestId>request-id</RequestId>
     <HostId>host-id</HostId>
     <BucketName>specified-bucket-name</BucketName>
     <Key>object-name</Key>
</Error>

The list below describes XML elements in an error response body.

• Error

  Root element.

• Code

  The error code.

• Message

  Text that provides more information about the error.

• RequestId

  The HCP-internal ID assigned to the request.

• HostId

  The HCP-internal ID of the host responding to the request.

• BucketName

  The specified bucket name. This element is included in the response body only when the error code is NoSuchBucket.

• Key

  The specified object name. This element is included in the response body only when the error code is NoSuchKey.

Every error response body contains an error code and a message that provides more information about the error. Error codes are returned in addition to HTTP status codes. A single HTTP status code can correspond to multiple error codes.

The table below describes the error codes that can be returned in response to S3 compatible API requests.