Skip to main content

REST API overview

The StorONE REST API lets you do over HTTPS what you do in the web interface and the CLI: provision storage, manage snapshots and replication, read monitoring data, configure notifications, and so on. It's the right tool when another system needs to drive StorONE — a provisioning pipeline, an orchestration tool, a monitoring integration, or your own scripts.

Every request runs as the user who logged in, with that user's roles, exactly as if they had run the matching command in the CLI. Nothing about the API gives a user more access than they have anywhere else.

How the API is organized

The API mirrors the CLI one-to-one. Each command that Customer-level users can run in the CLI has an endpoint, and the endpoint runs that command:

  • The path is the command path. Spaces become slashes, so the CLI command action_policies create is POST /action_policies/create, and applications volumes list is GET /applications/volumes/list.
  • The HTTP method follows the kind of command. Commands that list or view something are GET, commands that create are POST, commands that edit are PUT, and commands that delete are DELETE.
  • Parameters are the command's parameters. Parameters go in the query string for GET and DELETE, and in a JSON body for POST and PUT (a PUT also takes the item it edits, such as a name, in the query string).

Because of this, everything in the CLI chapters of this documentation also tells you how the operation behaves over REST: the same defaults, the same restrictions, and the same validation. The Endpoint Reference chapter lists every endpoint with its parameters.

Tip: If you know the CLI command and want its REST form, the CLI can show it to you: examples generate --command "applications volumes create" --convertToRest. See CLI productivity tools.

Where to find it

The API is served over HTTPS (port 443) by every node, at the node's management address:

https://<management-address>/

Each system also publishes an interactive reference, generated from the software version it's running, so it always matches the system you're talking to:

What Address
Interactive reference (Swagger UI) https://<management-address>/docs
OpenAPI definition (JSON) https://<management-address>/docs/v1/swagger.json

The Swagger page lets you try endpoints from your browser, and the OpenAPI definition can be imported into tools such as Postman, or fed to an OpenAPI client generator.

If your client doesn't trust the system's TLS certificate, install the certificate on the client. For quick tests only, most tools let you skip verification (for example, curl -k).

Quick start

Every session has three steps:

  1. Log in to get a session token: POST /login with a username and password. See Authentication.
  2. Call endpoints, sending the token in the Authorization header: Authorization: Bearer <token>. See Requests and responses for how requests and results are shaped.
  3. Log out when you're done: DELETE /logout.

For complete, copy-and-paste walkthroughs in curl, PowerShell, and Python, see Examples. Operations that take a while can run in the background; see Asynchronous operations.

What's different from the CLI

A few CLI commands exist only for the interactive session and have no endpoint. Most have a natural REST equivalent:

CLI command In REST
logout DELETE /logout
watch Call the GET endpoint on your own schedule.
replication continuous wait_sync Poll GET /replication/continuous/list.
configurations session async_completion Poll GET /configurations/session/list (see Asynchronous operations).
aliases, scripts, sleep, search, clear, exit, refresh, examples generate, settings output Features of the interactive CLI session; not needed over REST. Use outputType to choose an output format (see Requests and responses).
resources drives performance_analyzer CLI only.

Next: Authentication — logging in, session tokens, and logging out.

No comments to display