This section provides general information about the SCSP READ method that applies to both named and unnamed objects.

READ is a request to the storage cluster for a specific object. The READ request is formatted as an HTTP request using the GET method.

SCSP Method	HTTP Method	RFC 7231 Section

SCSP Method	HTTP Method	RFC 7231 Section
READ	GET	4.3.1

READ for Named Objects

GET /mybucket/samplefile.txt HTTP/1.1
Host: cluster.example.com
User-Agent: Swarm Client/0.1

READ for Unnamed Objects

GET /12BFEA648C2697A56FD5618CAE15D5CA HTTP/1.1 
Host: cluster.example.com 
User-Agent: Swarm Client/0.1

Swarm makes no assumptions about User-Agent (except it is an HTTP/1.1 client). The Host header is mandatory and must conform to the requirements of Section 14.23 in the HTTP/1.1 specification.

Error

Error loading excerpt from "WRITE for Unnamed Objects".

READ for Erasure-Coded Objects

Erasure coding objects on disk allows storing large objects in the cluster with a smaller storage footprint, compared to earlier versions of Swarm.

See Working with Large Objects.

READ is affected by the checkIntegrity=yes query argument used to verify all segments are found before executing the READ.

See SCSP Query Arguments.

READ with Content Validation

To validate the content during a read, add the query argument validate=yes to the URI:

GET /name-or-uuid?validate=yes HTTP/1.1
Host: cluster.example.com
User-Agent: Swarm Client/0.1

Using this argument, the content digest is computed and compared at the end. A hash mismatch causes the socket connection to be dropped before sending the final bytes.

READ for Node Status and Cluster Capacity

A READ request can be submitted without a name or UUID:

Using this argument returns counts for high-level node methods (READ, WRITE, DELETE, …), as well as cluster-wide Space Available and Total Capacity values.

This information is also available on the Node Status page that appears when navigating to a node's IP address with the designated SCSP port (for example, http://192.168.99.100:80).

READ with Range Headers

In some cases, an application may be interested in a byte portion of a larger object stored in Swarm. Rather than read the entire object and filter out the interesting parts, the application can include one or more Range headers with an SCSP READ request. A READ request can include more than one Range header.

See the HTTP/1.1 specification for a thorough discussion of Range headers.

Below are some examples and interpretations:

Range	Returns

Range	Returns
0-499	First 500 bytes of the object
500-999	The second 500 bytes
-500	Last 500 bytes
0-499, 500-999	First 1000 bytes

Note

Range headers are not compatible with either integrity seals or the ContentMD5 header because both require a hash of the object's entire contents. The connection is closed as if the integrity seal or the Content-MD5 was invalid if the range is not set to a value greater than or equal to the size of the object.

READ requests that include invalid Range headers (ranges not existing in the object) cause Swarm to respond with a 416 (Range not satisfiable) error. A successful response to a READ that includes one or more Range headers is 206 (Partial content). Data in the requested ranges are included in the 206 response.

READ requests that include a range such as Range: 0-199, 300-349, 500-999 returns a Content-Type: multipart/byteranges response consisting of three parts: 200, 50, and 500 bytes of content.

See 14.35 (Range) and Appendix 19.2 (Internet Media Type multipart/byteranges) in HTTP/1.1 RFC .

Note

Entering a range with the range in reverse order (where the end of the range is entered first) returns the entire object. For example, Range: 999-500 returns all content in the object. The range header is essentially ignored.