Page Comparison

Alias Objects

alias

yes/true to activate

On write requests, indicates an alias object is created.

The alias argument must be used with a POST method on an alias object and can optionally be included for other operations on alias objects.

Content Integrity

gencontentmd5

yes/true to activate

Computes the Content-MD5 for the body data of the request, returning the Content-MD5 as a header in the 201 Created response.
Replaces the Expect: Content-MD5 header, which is deprecated. (v9.2)

hash

hash value

A content integrity hash value provided on the request for validation. The case of this argument does not matter.

hashtype

newhashtype

{ md5 | sha1 | sha256 | sha384 | sha512 }

Specifies the value of an object's hash. The hashtype query argument may appear on a variety of requests to generate or validate a content hash value.

The newhashtype query argument is used to "re-seal" the content hash with one hash value while simultaneously checking another.

validate

yes/true to activate

Validate On Read (VOR). Reads an object with an integrity seal. See Content Seals and Validation. 

On GET, validates data read from disk has not been corrupted. Swarm closes the connection before all data is sent if this check fails.

Domains

createdomain

value ignored

[Deprecated: v9.2] Add to a WRITE to create the domain specified by domain=domain-name.

See Manually Creating and Renaming Domains.

domain

domain-name

Represents the domain name in some SCSP requests. Client applications most often send the domain name as the Host in the request. The domain argument can be supplied by the client to explicitly override any value from the Host request header when the Host header does not match the domain name. A domain argument always has precedence over the Host header in the HTTP/1.1 request.

The sole situation domain is required is for an SCSP method on a domain object itself. Neither domain nor Host are required for requests within the default cluster domain.

Erasure Coding (EC)

encoding

k:p

The integer values for the data (k) and parity (p) segment counts when specifying erasure coding.

erasurecoded

yes/true to override, no/false to inhibit

Used on EC writes to override the cluster's policy.ecMinStreamSize value.

• YES forces EC encoding for objects smaller than the cluster's minimum.

• NO prevents EC encoding on objects that may otherwise be erasure-coded.

Using erasurecoded without encoding or when the cluster is not configured for EC results in a 400 Bad Request.

segmentsize

integer

The maximum size (in bytes) of a segment in any erasure-encoded set for this object, overriding the ec.SegmentSize configuration setting. This value cannot be smaller than 100 MB.

segmentwidth

integer

Number of bytes. Allows ec.segmentWidth configuration value to be modified per request.

Listing Consistency

index

yes/true to activate, no/false to inhibit

Appears on Gateway requests when enabling the Gateway Configuration option EnhancedListingConsistency. (v9.3)

Optionally supplied on a POST, PUT, COPY, APPEND, or DELETE request. Performs synchronous search indexing of the newly written/deleted object.

sync

now or wait to activate, no/false to inhibit

Appears on Gateway requests when enabling the Gateway Configuration option EnhancedListingConsistency. (v9.3)

Optionally used on a listing query GET request to force consistency of results returned on the listing.

• now performs a refresh on the index in Elasticsearch immediately before preforming the listing query.

• wait delays execution of the listing query to provide Elasticsearch time to refresh the index.

Metadata

preserve

yes/true to activate

Works with COPY, PUT, and APPEND requests to verify custom metadata existing on the object is carried over on the write (see Custom Metadata Headers). Include the header name with the new value on the request to overwrite an existing value. Cannot be used with replace. (v9.2, v9.5)

replace

yes/true to activate

Works with APPEND requests to remove any custom metadata existing on the object on the write, overriding the default APPEND behavior to preserve them (see Custom Metadata Headers). Include the header name with the new value on the request to add new metadata. Cannot be used with preserve. (v9.5)

Named Objects

newname

{new name for object, bucket, domain}

Provides a new name (within the same bucket) for an update request (PUT, COPY, APPEND) on a named object. Requests for the original name return a 404 Not Found and the prior search metadata is removed after renaming an object.

'Subdirectory' names are part of the object name, so they must be included as part of a newnamequery argument. The bucket name stops at the first slash. Everything after the first slash, including other slashes, is part of the object name.

newnamealso allows renaming domains and buckets. See Renaming Domains and Buckets.

putcreate

yes/true to activate, no/false to inhibit

Allows use of HTTP PUT Create to create new named objects if set to yes. There is no need to add the putcreate query argument if the scsp.allowPutCreate storage setting is enabled.

Directs Swarm to treat the request as a regular PUT if set to no, generating a 404 Not Found error if the named object does not exist.

See SCSP WRITE.

Multipart Write

inprogress

yes/true to activate

On a multipart PATCH complete, postpones HP segment consolidation until the object is completed again without the query argument, or by another method, such as COPY. (v9.4)

shrink

On a multipart PATCH, required if the patch reduces the size of the object. (v9.4)

partnumber

integer

On a multipart POST, indicates the part number of a multipart upload in progress. (v7.0)

uploadid

upload id

On a multipart POST or DELETE, identifies all requests associated with a single multipart upload. It returns the ID as a 98-byte string. (v7.0)

uploads

yes/true to activate

On a multipart POST, PUT, or APPEND, indicates the request is a multipart upload write initiate. (v7.0)

Recursive Delete

recursive

yes/true to flag for deletion

now for immediate reclamation

Required on DELETE of a bucket or domain (context). Indicates when the health process may begin asynchronously reclaiming any content contained in the deleted context.

This request creates a grace period based on the health.recursiveDeleteDelay Storage setting (the default is one week) unless using recursive=now. This grace period allows recreation of a bucket or domain before the content is lost. The health processor begins deleting all content contained in the deleted domain or bucket after the grace period ends. A critical error is logged indicating the object can be neither deleted nor accessed without the parent context if the deleted domain or bucket contains indelible objects. Added in v7.0. 

Replicate on Write (ROW)

count

integer

Used to affect the replicate=immediate behavior.

replicate

immediate, full, integer

Controls the response behavior to a POST, PUT, COPY, or APPEND request for a replicated object.

• immediate – Two replicas must be created before Swarm sends the response; if more replicas are required, those additional replicas are created after the response.

• full – All required replicas must be created before Swarm sends the response.

• integer – Specifies the number of replicas to be created. As with immediate, two replicas must be created before Swarm sends the response. Swarm uses the smaller of those values if policy.replicas max or the lifepoint reps is less than this integer. 

The above rules apply with scsp.maxContextReplicas taking the place of policy.replicas max if the object in the request is a bucket or a domain.

SEND

feedid

feedtype

all | integer

all | search | replication | s3backup

Specifies one or more specific feeds (feedid=1&feedid=3) as the replication destination. Open the Swarm UI, select Cluster > Feeds, and locate the ID column to find existing feed IDs.

Specifies one or more types of feeds as the replication destination, from among these values: search, replication, s3backup. 

Use the special value “all” to refer to all feed IDs or types, including no feed.

The SEND request needs query arguments for feedid, feedtype, or both, which is a union of all provided arguments; if neither are provided, SEND reverts to the legacy behavior. 

timeout

true | number of seconds | false

Sets how long to wait for replication to complete; if disabled (false; not recommended), feed processing can go on indefinitely if a feed is blocked. 

Using timeout=true waits for the Swarm setting scsp.defaultFeedSendTimeout time in seconds, which defaults to 30. Specifying a positive number for the timeout overrides the value in the Swarm setting.

force

true | false | yes | no

If the value is true or yes, Swarm forces re-processing of the object though any associated feeds for objects previously processed.

Versioning

version

ETag of desired object version

Used on GET, HEAD, DELETE, COPY, APPEND, or SEND requests to specify a previous version to target on the request: version={etag}

Operations referencing the current version proceed normally if used in contexts where versioning is disabled, but any other ETag results in a 404 - Not Found. (v9.2)

The query succeeds if the query argument value is the UUID (and ETag) of the object if used on GET or HEAD requests of an immutable object (which cannot be versioned). (v9.5)

suspendversioning

Allows temporary suspension of version creation on POST, PUT, COPY, APPEND, and DELETE requests for versioned objects. It has the effect of updating the current version without adding to the versioning chain. (v9.5)