Requests and responses

Requests

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 responsesoutputType), 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.