Request contents (GET object or object versions)

The GET request to retrieve an object has these elements:

If you’re accessing the namespace as an authenticated user, an Authorization header

The URL of the object or symbolic link

By default, the GET request to retrieve object versions does not include delete markers (that is, the marker versions that indicate when an object was deleted). To retrieve a listing that includes delete marker, specify this URL query parameter:

deleted=true

You can also specify deleted=false, which results in the default behavior.

Requesting a specific old version

To retrieve a specific old version of an object, specify the version URL query parameter with the ID of the version you want. You can omit this parameter to retrieve the current version of an object.

To find the ID of the version you want, list the versions of the object. For more information about listing the versions of an object, see Listing object versions.

Requesting the latest version at a specified time

To retrieve the latest version of an object that existed at a specified time, specify the version URL query parameter with your target ingest time. You can omit this parameter to retrieve the current version of an object.

To find the ingest time of the version you want, list the versions of the object. For more information about listing the versions of an object, see Listing object versions.

You can also use a GET request to retrieve the timestamp or timestamp range of an object, which you can use to find a version of that object.

Requesting a range of versions using version IDs

To retrieve a range of versions of an object using their version ID numbers, specify the version URL query parameter with the range of object version IDs you want. You can omit this parameter to retrieve the current version of an object.

To find the ID of the versions you want, by listing the versions of the object, see Listing object versions.

The version query parameter with version ID range has this format:

?version=StartVersionID-EndVersionID

The table below shows the ways in which you can specify the range.

Range specification Description Example

start-version-id
end-version-id

Version ID, exclusive, in start-version-id through end-version-id, inclusive

Object versions beginning with 91728994268353 through object version 91728994618369: 91728994268354–91728994618369

start-version-id

Version ID in start-version-id through the end of the object versions

All object versions beginning with 91728994618369 and continuing through the end of the object versions: 91728994618370–

0– All version IDs All object versions: 0–

These rules apply to the version ID range query parameter:

If you omit the parameter, HCP retrieves the current version of an object.

If you specify a valid range, HCP returns the requested amount of data with a status code of 200.

Requesting a range of versions using ingest timestamps

To retrieve a range of versions of an object using their ingest timestamps, specify the version URL query parameter with the range of version ingest timestamps you want. You can omit this parameter to retrieve the current version of an object.

To find the creation timestamps of the versions you want, by listing the ingest timestamps of the versions, see Listing object versions.

The version query parameter with create timestamp range has this format:

?version=@start-Create-Time-Millis-@end-Create-Time-Millis

The table below shows the ways in which you can specify the range.

Range specification Description Example

@start-Create-Time-Milliseconds
@end-Create-Time-Milliseconds

Version timestamp in start-Create-Time-Milliseconds, exclusive, through end-Create-Time-Milliseconds, inclusive

Object versions beginning at ingest timestamp 1493911519817 through ingest timestamp 1493911519820: @1493911519817–@1493911519820

@start-Create-Time-Milliseconds

Version timestamp in start-Create-Time-Milliseconds through the end of the object versions

All object versions beginning at ingest timestamp 1493911519817 and continuing through the end of the object versions: @1493911519817–

@0- All timestamps All object version timestamps: @0–

These rules apply to the version creation timestamp range query parameter:

If you omit the parameter, HCP retrieves the current version of an object.

If you specify a valid range, HCP returns the requested amount of data with a status code of 200.

Conditionally retrieving an object or version

To retrieve an a single object or version only if the object meets certain conditions, use the headers listed in Conditional operations.

Forcing the generation of an ETag

To force HCP to generate an ETag for an object that does not yet have one, specify a forceEtag URL query parameter with a value of true. For more information see Conditional operations.

Requesting data in compressed format

To request that HCP return a single object or version in gzip-compressed format, use an Accept-Encoding header containing the value gzip or *. The header can specify additional compression algorithms, but HCP uses only gzip.

You can request a single object or version data in compressed format with any of the additional request elements described in the sections below.

Choosing not to wait for delayed retrievals

HCP may detect that a GET request will take a significant amount of time to return an object. You can choose to have the request fail in this situation instead of waiting for HCP to return the object. To do this, use the nowait URL query parameter.

When a GET request fails because the request would take a significant amount of time to return an object and the nowait parameter is specified, HCP returns an HTTP 503 (Service Unavailable) error code.

Tip: If the request specifies nowait and HCP returns a 503 error code, retry the request a few times, waiting about thirty seconds in between retries.

Retrieving object data and an annotation together

To retrieve a single object or version data and one annotation with a single request, specify these elements:

A type URL query parameter with a value of whole-object.

An annotation URL query parameter with a value of the name of the annotation. You can omit this parameter for the default annotation.

Optionally, an X-HCP-CustomMetadataFirst header specifying the order of the parts. Valid values are:

otrue — The annotation should precede the object data.

ofalse — The object data should precede the annotation.

The default is false.

Requesting partial object data

To retrieve only part of a single object or version data, specify an HTTP Range request header with the range of bytes of the object data to retrieve. You specify the Range header in addition to other request elements described above. The first byte of the data is in position 0 (zero), so a range of 1-5 specifies the second through sixth bytes of the object, not the first through fifth.

The Range header has this format:

Range: bytes=range

The table below shows the ways in which you can specify the range.

Range specification Description Example

start-position
end-position

Bytes in start-position through end-position, inclusive. If end-position is greater than the size of the data, HCP returns the bytes in start-position through the end of the data.

Five hundred bytes beginning with the two-hundred-first: 200–699

start-position

Bytes in start-position through the end of the object data.

All the bytes beginning with the seventy-sixth and continuing through the end of the object data: 75–

offset-from-end

Bytes in the offset-from-end position, counted back from the last position in the object data, through the end of the object data.

The last 25 bytes of the object data: –25

These rules apply to the Range header:

If you omit the Range header, HCP returns the complete object data.

If you specify a valid range, HCP returns the requested amount of data with a status code of 206.

If you specify an invalid range, HCP ignores it and returns the complete object data, with a status code of 416.

You cannot request partial object data with custom metadata in the same request. If the request includes a Range header and a type=whole-object query parameter, HCP returns a status code of 400.

Checking whether an object or version has been replicated

The response to a GET request for an object or version can include the X-HCP-Replicated header. The value of this header can be true or false, indicating whether the object or version has been replicated. Including this header in the response increases the time required to process the GET request.

Whether HCP returns the X-HCP-Replicated header by default depends on the system configuration. You can override the default by including the X-HCP-Get-Replicated header in the GET request. For the value of this header, specify:

true to include the X-HCP-Replicated header in the response

false to exclude the X-HCP-Replicated header from the response

© 2015, 2020 Hitachi Vantara LLC. All rights reserved.