Read-only ONTAP REST learning · version-specific schema and asynchronous changes
Example: query storage volumes on a lab cluster. Replace host and SVM; use a named least-privilege account and a trusted CA certificate.
About the command and output examples
Names, addresses and results are illustrative. Commands have not been executed against a live storage system or SAN switch for this publication. Confirm syntax and compatibility for your release, then rehearse in an approved lab. Existing-data recovery and destructive changes need an environment-specific plan. Read the editorial standards.
01Prepare access
- Confirm ONTAP version and supported endpoint in the REST API reference. Create an account or role with only the required permissions. Use HTTPS with valid certificate validation.
- Keep secrets out of scripts and repositories. Prefer a secure credential store or an approved environment mechanism. Never publish real cluster addresses or tokens on this public site.
Authenticated access to the API documentation on a lab cluster.
02Read before write
- Query a small collection with field selection or filters and inspect the response object, pagination and job state.
- For changes, use a test SVM/volume and follow the endpoint schema. Review idempotency, asynchronous jobs and error handling.
curl --fail --silent --show-error \
--cacert /path/to/cluster-ca.pem \
--user "${ONTAP_USER}" \
"https://cluster.example.com/api/storage/volumes?fields=name,svm.name,state&max_records=20"03Validate and log
- Compare API output with System Manager or CLI for the same object. For asynchronous changes, poll the returned job until success or error.
- Record request ID, response status and object UUID without logging credentials. Roll back test changes using the documented API workflow.
Script handles non-2xx responses, pagination and asynchronous completion.
04Read a response as a contract, not as a screen scrape
Use the API reference and the API documentation on the actual cluster to identify supported endpoints and fields. An empty records array, an authentication failure and a partially paginated result are different outcomes. Preserve them as different collector states; otherwise a failed request can become an apparently empty, healthy inventory.
| Response condition | Required handling |
|---|---|
| 200 with records | Process records and follow the collection’s next link until complete. |
| 200 with no next link | Collection is complete; this does not prove service health. |
| 401/403 | Report authentication/authorization failure; do not return green health. |
| 429/503 | Use bounded retry/backoff according to the documented API behavior. |
| 202 with job link for a change | Poll the documented job until terminal success/failure or a reported timeout. |
| TLS validation error | Repair trust, hostname or expiry; do not silently disable validation. |
- Run a small field-selected read with the supplied secure curl pattern. Compare the object UUID and name with System Manager/CLI.
- Follow only validated same-origin pagination/job links. A script sending credentials must not forward them to an arbitrary external hostname supplied in a response.
- For a controlled change, record the returned object/job identity and verify final object state after success. A transport timeout does not prove the server never performed a POST; discover the result before retrying creation.
05An illustrative paginated response and completion test
The record count above is one page’s count. A script that stops here may omit later volumes. The provided Python and PowerShell inventory guides include collection handling; verify their output against a known multi-page test inventory and exercise an authentication error. Use a bounded job polling deadline and report timeout as unknown/incomplete, retaining the job UUID for reconciliation.
{
"records": [{"name": "vol_projects", "state": "online"}],
"num_records": 1,
"_links": {"next": {"href": "/api/storage/volumes?start=example"}}
}The script distinguishes complete, failed and unknown results; pagination, trust and a job failure/timeout have explicit handling.
Use the section links to revisit a step, or follow a related guide below.
Official references and further reading
Choose the matching release in the vendor documentation before using a command or design. References open on the publisher’s website; linked material remains with its publisher.