1 General Request Response
2 Version Response
3 Cluster Usage Response
4 Tenant, Domain Listing Response
5 ETC Listing Response
- 5.1 Document Listing Response Format
6 Token Response Formats
- 6.1 Token Listing Response Format

These are the Content Management API response formats that can be returned with a request. The order of the JSON fields in output records and the ordering of lists is not defined unless otherwise noted.

Best Practice

Make applications tolerant of extra fields in all responses for future compatibility.

General Request Response

This is the general-purpose response format for requests when no other specific format is defined. This response is also given when errors occur preventing the return of a specific response format. This general request response format is used to communicate the error condition if a listing operation fails.

The response is a JSON formatted body whose fields and HTTP status codes are defined as follows:

General Request Response Format

message	human-readable message describing response
code	text response code
errors	array of strings with error details

Response Code Text Strings

WriteSucceeded	201 status code
DeleteSucceeded	200 status code
CreateFailed	various status codes from storage cluster
ListFailed	various status codes from storage cluster
ReadFailed	various status codes from storage cluster
WriteFailed	various status codes from storage cluster
DeleteFailed	various status codes from storage cluster
NotAuthorized	401 or 403 status code
ServerError	500 status code
MissingParameter	400 status code; missing required query argument
NotFound	404 status code; message contains path
OtherError	various status codes; non-specific error
BadJson	400 status code; JSON unable to be parsed
InvalidJson	400 status code; JSON did not validate
BadRequest	400 status code; invalid argument or path

This is an example response:

{
  "message": "The data were not parsable JSON.",
  "code": "BadJson",
  "errors": [
    "Unexpected character ('P' (code 80)): expected a valid value 
          (number, String, array, object, 'true', 'false' or 'null')\n at 
          [Source: [B@37994099; line: 1, column: 2]"
  ]
}

Version Response

The version response contains information about the Management API software version. A general request response is given if an error occurs on the request.

manageApiVersion	API version string; format not defined

This is an example version response:

{
  "manageApiVersion": "1.0"
}

Cluster Usage Response

The cluster usage response contains storage usage information about the back-end Swarm object storage cluster. A general request response is given if an error occurs on the request.

availableGb	Storage GBytes available; integer
capacityGb	Total storage GBytes in the cluster; integer

This is an example version response:

{
    "availableGb": 31676,
    "capacityGb": 512437
}

Tenant, Domain Listing Response

The tenant and domain listing response returns a listing of tenants and storage domains as a JSON list object. A general request response is given if an error occurs on the request.

name	Name of tenant or domain
etag	ETag opaque string; strong validator
contentMd5	base64 encoded MD5 value
lastModified	ISO 8601 format date and time with sub-second resolution

This is an example of a storage domain listing:

ETC Listing Response

The ETC listing response returns a listing of documents associated with a tenant or storage domain as a JSON list object. A general request response is given if an error occurs on the request.

Document Listing Response Format

name	Name of tenant or domain
etag	ETag opaque string; strong validator
contentMd5	base64 encoded MD5 value
lastModified	ISO 8601 format date and time with sub-second resolution

This is an example of a listing of etc documents:

Token Response Formats

There are two types of token response formats: individual token GET/PUT response and token listing response. Both response formats are JSON documents. The token listing response is a JSON array of individual token objects.

owner	User name for whom this token applies
scope	Root (blank), tenant, or storage domain scope
token	Token identification; opaque value
secret	Optional S3 secret key; supplied during create
expiration	Token expiration in ISO 8601 format date and time with sub-second resolution
creation	Token creation in ISO 8601 format date and time with sub-second resolution

This is an example of a token response:

Token Listing Response Format

The format of the token listing response is a JSON array of token objects. By default, the token listing response does not include the secret fields for the tokens.

Swarm Documentation

Management API Response Formats