Skip to main content
A newer release of this product is available.

StorageGRID Swift REST API operations

Contributors netapp-perveilerk netapp-lhalbert
PDFs

There are operations added on to the Swift REST API that are specific to StorageGRID system.

GET container consistency request

Consistency level provides a balance between the availability of the objects and the consistency of those objects across different Storage Nodes and sites. The GET container consistency request allows you to determine the consistency level being applied to a particular container.

Request

Request HTTP Header Description

X-Auth-Token

Specifies the Swift authentication token for the account to use for the request.

x-ntap-sg-consistency

Specifies the type of request, where true = GET container consistency, and false = GET container.

Host

The hostname to which the request is directed.

Request example

GET /v1/28544923908243208806/Swift container
X-Auth-Token: SGRD_3a877009a2d24cb1801587bfa9050f29
x-ntap-sg-consistency: true
Host: test.com

Response

Response HTTP Header Description

Date

The date and time of the response.

Connection

Whether the connection to the server is open or closed.

X-Trans-Id

The unique transaction identifier for the request.

Content-Length

The length of the response body.

x-ntap-sg-consistency

The consistency control level being applied to the container. The following values are supported:

  • all: All nodes receive the data immediately or the request will fail.

  • strong-global: Guarantees read-after-write consistency for all client requests across all sites.

  • strong-site: Guarantees read-after-write consistency for all client requests within a site.

  • read-after-new-write: Provides read-after-write consistency for new objects and eventual consistency for object updates. Offers high availability and data protection guarantees.

    Note: If your application uses HEAD requests on objects that do not exist, you might receive a high number of 500 Internal Server errors if one or more Storage Nodes are unavailable. To prevent these errors, use the “available” level.

  • available (eventual consistency for HEAD operations): Behaves the same as the “read-after-new-write” consistency level, but only provides eventual consistency for HEAD operations. Offers higher availability for HEAD operations than “read-after-new-write” if Storage Nodes are unavailable.

Response example

HTTP/1.1 204 No Content
Date: Sat, 29 Nov 2015 01:02:18 GMT
Connection: CLOSE
X-Trans-Id: 1936575373
Content-Length: 0
x-ntap-sg-consistency: strong-site
Related information

Use tenant account

PUT container consistency request

The PUT container consistency request allows you to specify the consistency level to apply to operations performed on a container. By default, new containers are created using the “read-after-new-write” consistency level.

Request

Request HTTP Header Description

X-Auth-Token

The Swift authentication token for the account to use for the request.

x-ntap-sg-consistency

The consistency control level to apply to operations on the container. The following values are supported:

  • all: All nodes receive the data immediately or the request will fail.

  • strong-global: Guarantees read-after-write consistency for all client requests across all sites.

  • strong-site: Guarantees read-after-write consistency for all client requests within a site.

  • read-after-new-write: Provides read-after-write consistency for new objects and eventual consistency for object updates. Offers high availability and data protection guarantees.

    Note: If your application uses HEAD requests on objects that do not exist, you might receive a high number of 500 Internal Server errors if one or more Storage Nodes are unavailable. To prevent these errors, use the “available” level.

  • available (eventual consistency for HEAD operations): Behaves the same as the “read-after-new-write” consistency level, but only provides eventual consistency for HEAD operations. Offers higher availability for HEAD operations than “read-after-new-write” if Storage Nodes are unavailable.

Host

The hostname to which the request is directed.

How consistency controls and ILM rules interact to affect data protection

Both your choice of consistency control and your ILM rule affect how objects are protected. These settings can interact.

For example, the consistency control used when an object is stored affects the initial placement of object metadata, while the ingest behavior selected for the ILM rule affects the initial placement of object copies. Because StorageGRID requires access to both an object's metadata and its data to fulfill client requests, selecting matching levels of protection for the consistency level and ingest behavior can provide better initial data protection and more predictable system responses.

The following ingest behaviors are available for ILM rules:

  • Strict: All copies specified in the ILM rule must be made before success is returned to the client.

  • Balanced: StorageGRID attempts to make all copies specified in the ILM rule at ingest; if this is not possible, interim copies are made and success is returned to the client. The copies specified in the ILM rule are made when possible.

  • Dual Commit: StorageGRID immediately makes interim copies of the object and returns success to the client. Copies specified in the ILM rule are made when possible.

Note Before selecting the ingest behavior for an ILM rule, read the full description of these settings in the instructions for managing objects with information lifecycle management.

Example of how consistency control and ILM rule can interact

Suppose you have a two-site grid with the following ILM rule and the following consistency level setting:

  • ILM rule: Create two object copies, one at the local site and one at a remote site. The Strict ingest behavior is selected.

  • Consistency level: “strong-global” (Object metadata is immediately distributed to all sites.)

When a client stores an object to the grid, StorageGRID makes both object copies and distributes metadata to both sites before returning success to the client.

The object is fully protected against loss at the time of the ingest successful message. For example, if the local site is lost shortly after ingest, copies of both the object data and the object metadata still exist at the remote site. The object is fully retrievable.

If you instead used the same ILM rule and the “strong-site” consistency level, the client might receive a success message after object data is replicated to the remote site but before object metadata is distributed there. In this case, the level of protection of object metadata does not match the level of protection for object data. If the local site is lost shortly after ingest, object metadata is lost. The object cannot be retrieved.

The inter-relationship between consistency levels and ILM rules can be complex. Contact NetApp if you require assistance.

Request example

PUT /v1/28544923908243208806/_Swift container_
X-Auth-Token: SGRD_3a877009a2d24cb1801587bfa9050f29
x-ntap-sg-consistency: strong-site
Host: test.com

Response

Response HTTP Header Description

Date

The date and time of the response.

Connection

Whether the connection to the server is open or closed.

X-Trans-Id

The unique transaction identifier for the request.

Content-Length

The length of the response body.

Response example

HTTP/1.1 204 No Content
Date: Sat, 29 Nov 2015 01:02:18 GMT
Connection: CLOSE
X-Trans-Id: 1936575373
Content-Length: 0
Related information

Use tenant account