Page Comparison

Alias Objects

alias

yes/true to activate

On write requests, indicates that an alias object should be 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

hash

hash value

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

hashtype

newhashtype

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 that the data read from disk has not been corrupted. If this check fails, Swarm closes the connection before all of the data is sent.

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. When the Host header does not match the domain name, the domain argument can be supplied by the client to explicitly override any value from the Host request header. A domain argument always has precedence over the Host header in the HTTP/1.1 request.

The only time domain is required is for an SCSP method on a domain object itself. Neither domain nor Host is 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 might otherwise be erasure-coded.

Using erasurecoded without encoding or when the cluster is not configured for EC will result 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.

Appears on Gateway requests when you enable 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.

now or wait to activate, no/false to inhibit

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

Optionally used on a listing query GET request to force consistency of results that are 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 in order to give Elasticsearch time to refresh its index.

Named Objects

newname

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

Remember that 'subdirectory' names are part of the object name, so they must be included as part of a newnamequery arg. The bucket name stops at the first slash, and everything after the first slash, including other slashes, are part of the object name.

newname also lets you rename domains and buckets. See Renaming Domains and Buckets.

putcreate

Multipart Write

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 that the request is a multipart upload write initiate. (v7.0)

Recursive Delete

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.

Unless you use recursive=now, this request creates a grace period based on the health.recursiveDeleteDelay Storage setting (the default is one week). This grace period lets you recreate a bucket or domain before its content is lost. After the grace period ends, the health processor will begin deleting all of the content contained in the deleted domain or bucket. If the deleted domain or bucket contains undeletable objects, a critical error is logged that the object can be neither deleted nor accessed without its parent context. 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 – Only 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 of the 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. However, if policy.replicas max or the lifepoint reps is less than this integer, then Swarm uses the smaller of those values. 

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

feedid

feedtype

all | integer

all | search | replication | s3backup

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

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 of those provided arguments; if you do not provide either, SEND reverts to the legacy behavior. 

Sets how long to wait for replication to complete; if disabled (false; not recommended), feed processing could 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.

Versioning

version

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

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

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