Requests and responses

Every endpoint follows the same conventions, so once you've made one call you know how to make them all. This page covers how to send parameters, the two generic parameters (async and outputType), and how to read results and errors.

Making a request

Send the session token with every request (see Authentication):

Authorization: Bearer <SessionToken>

Where the parameters go depends on the HTTP method:

Method	Used for	Parameters go in
GET	Listing and viewing	The query string.
DELETE	Deleting	The query string.
POST	Creating	A JSON body (Content-Type: application/json).
PUT	Editing	A JSON body, plus the item being edited, such as its name, in the query string.

The Endpoint Reference shows, for each endpoint, which parameters are query parameters and which are body fields. Use the names exactly as they appear there: query parameters are written like the CLI's options (onlyMyPendingActions), and body fields start with a capital letter (MinimumRequiredReviewers).

A few rules of thumb:

• Lists. A query parameter that takes several values is repeated: ?hosts=host1&hosts=host2. In a JSON body, use a JSON array.
• Flags. A CLI flag such as --force is a boolean: force=true in the query string, or "Force": true in a body.
• Paired flags. Where the CLI has a pair of opposite flags (such as --enable_vss and --disable_vss), REST has one boolean field instead: true applies the first flag, false applies the second, and leaving it out applies neither. The reference notes this wherever it applies.
• Units. Fields whose names end in InBytes, InPercentage, InSec, or InMinutes take plain numbers in that unit. (The CLI accepts friendlier forms such as 2TB, but REST takes the plain number.)

The response envelope

Every endpoint returns a JSON object with the same top-level fields:

Field	Description
Status	The outcome, as text. Ok means the operation succeeded.
Result	The data returned by the operation (see below).
ErrorMessage	A description of what went wrong, when Status isn't Ok.
StringResult	Text output, for operations that return plain text rather than structured data.

For example, a successful GET /action_policies/list returns something like this (abbreviated):

{
  "Status": "Ok",
  "Result": {
    "ActionPolicyElement": [
      {
        "Id": 1183,
        "Name": "Volume Delete",
        "EntityType": "Volume",
        "OperationType": "Delete",
        "MinimumRequiredReviewers": 2,
        "AuthorizedReviewers": ["alice", "bob", "carol"]
      }
    ]
  }
}

Lists

When an endpoint returns a list of items, Result is an object with one property that holds the array. The Endpoint Reference names that property for each list endpoint where it's fixed, and lists the fields each item contains.

Operations that change something

Create, edit, and delete endpoints return the envelope with Status set to Ok when the change was made, or to a failure status with the reason in ErrorMessage. By default, the request waits for the operation to finish before it returns. To start it and return immediately instead, see Asynchronous operations.

Always check Status

The HTTP status code alone doesn't tell you whether an operation worked. A request that reaches the system and is refused or fails still returns 200 OK, with the reason in the body:

{
  "Status": "Fail",
  "ErrorMessage": "Action policy is already configured for: Volume Delete"
}

The HTTP status code is 401 Unauthorized only for authentication problems: a wrong password, a missing second factor, or an unknown or expired session token (see Authentication). So for every response, check the HTTP status for 401, and then check that Status is Ok.

Status	Meaning
Ok	The operation succeeded.
Fail	The operation failed. ErrorMessage explains why.
InvalidCommand	A parameter was missing, invalid, or not allowed together with another. ErrorMessage says which.
NotExist	The item you named doesn't exist.
Busy	The system can't take the request right now. Try again shortly.
MissingAuthenticationHeader, InvalidAuthorizationHeader	The Authorization header is missing or malformed.
SessionTokenDoesNotExist, DisposedSession	The session has expired, been logged out, or ended. Log in again.

Choosing an output format

GET endpoints take an optional outputType query parameter, which chooses how the result is returned. The default, Json, returns the envelope described above. The other values return the same data as formatted text, in the formats the CLI offers:

outputType	Format
Json	The JSON envelope (default).
Csv	Comma-separated values.
Xml	XML.
Yaml	YAML.
Table	A text table, as in the CLI.
Tree	A text tree, as in the CLI.
Prometheus	Prometheus format.

With any value other than Json, the response body is just the formatted text, without the envelope.

Other parameters

Create, edit, and delete endpoints also accept an async query parameter (see Asynchronous operations). Swagger also shows an uncommitAndAggregateId parameter on these endpoints; it isn't needed for normal use, so leave it unset.

---

Next: Asynchronous operations — running long operations in the background and checking on them.