Let's review some key things about RESTful APIs and how they're implemented in ONTAP:

If you're already familiar with the ONTAPI API (also known as ZAPI), there are some similarities between ONTAP REST APIs and ONTAPI. For example:

However, there are important differences between REST APIs and the ONTAP CLI and ONTAPI that you should understand as well:

In accordance with RFC3986 Section 5.2.4, ONTAP REST API removes dot segments to resolve the path. The examples below describe this behavior.

This request uses non-URL-encoded dots:

The previous request is resolved to this:

In the previous example, the volume information is returned rather than the file. Users should be cautious when using non-URL-encoded ".." since it can cause accidental data loss when making a delete request.

This request is interpreted as a delete to the volume rather than the file because of ...

To avoid this issue, dots should be URL-encoded to %2E. The previous request should look like this:

ONTAP REST APIs use HAL as the mechanism to support Hypermedia as the Engine of Application State (HATEOAS). When an object or attribute is returned that identifies a specific resource, a HAL-encoded link is also returned so that you can easily discover resources and be able to obtain more details about the resource.

The following is a list of all the globally supported query parameters. This list is intended as a quick reference for syntax purposes. The query parameters are described in more detail in other sections of this documentation. Note that multiple queries can be combined using an "&".

Although they are not documented as individual methods in the list of REST APIs, every API supporting POST, PATCH, or DELETE, also supports operations on multiple records in the collection. These collection based operations can be specified as either a list of records, allowing each record to be mutated individually, or as a query that applies the same change to multiple records in the collection.

APIs supporting POST, PATCH, or DELETE support these operations on the collection itself by specifying a records array in the JSON body. Each entry in this array must match the schema of an individual record of the API. Parsing failures are returned synchronously. All other validations are performed asynchronously, including those that are usually returned synchronously for asynchronous APIs.

POST and PATCH make a best-effort attempt to perform the operation atomically by rolling back any changes made to prior records if an operation on a later record fails. This behavior can be overridden via the continue_on_failure query parameter. When this parameter is true (default: false), the job performs the operation on every input record regardless of prior failures. If any failures are encountered in continue_on_failure mode, they are reported as the result of the job, but the successfully mutated records are not rolled back. DELETE operations do not attempt to roll back failures and always operate in continue_on_failure mode.

Most APIs support performing operations in parallel, and record-based operations take advantage of this, operating on multiple of the provided records at once. If there is some interdependence between the provided records, such as a hierarchical set of objects, the serial_records=true query parameter can be used to force the operation to be performed in order. APIs that do not support parallel operations run serially, by default. From a job tracking perspective, there is no difference between these two modes other than the speed at which the operation completes.

Unless the records array is directly documented in the API as synchronous, every record-based operation is performed as a job and follows the usual rules for asynchronous jobs. In addition to the usual /api/cluster/jobs record of the job, these operations return a job results href link. The link refers back to the API on which the operation was performed and can be followed after the job is complete. Job results include the current state of the records and fields operated on by the job. If a POST operation was successful on a record, that record is included in job results. If a DELETE operation was successful, that record is not included in the job results because it is no longer part of the collection. The same concept applies to failures. If the POST of a record fails, the record is not included in the job results because it is not part of the collection. The results also include any errors or rollback errors encountered by the job. The job results link is also returned as the Location header from a record-based POST job, supporting the same pattern for determining any generated identifiers as a single record POST. Note that the job results link does not support all of the usual GET features. Requesting specific fields and querying a subset of the records is supported, but max_records and return_timeout as well as other such query parameters for controlling the iteration of the collection is are not supported.

For PATCH and DELETE, any unique identifiers not included in the URI must be included in the JSON body of each record. For example, to DELETE a single volume, the API is usually /api/storage/volumes/{uuid}. To delete multiple volumes via a records array, the API is /api/storage/volumes, and the UUID of each volume is included in the JSON body of each record. For sub-endpoints with unique identifiers embedded in the path, such as /api/storage/volumes/{volume.uuid}/files/{path}, the volume.uuid is included once in the URI and is not included in each record. The path is included with each record.

Note that the LUN that was not rolled back is reported as being present in the results because it now exists in the collection.

ONTAP Error Response Codes

APIs supporting PATCH or DELETE requests on a resource instance also support PATCH or DELETE on the collection, as long as at least one field is specified in the query portion of the URL. A PATCH or DELETE request issued on a collection is equivalent to internally doing a query-based GET, followed by a serial PATCH or DELETE operation on each matching record. However, it only does the operation for return_timeout seconds, which is 15 seconds, by default. If a query-based operation is not completed before return_timeout seconds, the API returns a next link. The client must use the next link with the same HTTP method to continue the operation. Query-based operations will not continue to the next record until the operation on the prior record is completed, even for operations that are normally asynchronous.

Records may either be filtered by performing queries that only apply to a single field at a time (though multiple of such queries may be done simultaneously for different fields), or by applying queries that search across a set of fields for a value fulfilling a single specified query.

You can filter the results of a GET call using any attribute. The supplied query can either be for an exact value or can leverage special query operators.

Filtering allows you to select objects where the specified field matches the supplied query, or which can contain wildcards, ranges, negations, or an OR-defined list of the above. The special query operators include the following:

The special query characters above can be treated literally, with no special meaning, by enclosing the value in either double quotes or curly brackets. In order to escape double quotes or curly brackets and treat it literally you must enclose them with curly brackets.

Cross-field queries are useful when multiple fields should be searched for a value or some combination of values. Whereas traditional queries only allow a single field to be searched for a value, cross-field queries will return rows where any field in a specified set of fields matches the query. Cross-field queries may only be used for GET requests.

The fields to be queried across are specified in the "query_fields=" parameter. This should be a comma-delimited list of fields, or simply * to search across all fields. To specify the query to use in the search, pass in the "query=" parameter to a GET request with the string to use as the query. Fields may also be excluded from searching prefixing with '!'. This is useful if all fields are specified with '*', and then certain fields wish to be excluded, or if an an entire object was queried, to exclude certain sub-fields.

The query string represents a pattern to search for in all fields specified.

The * character is used to indicate wildcard character matching. * matches 0 or more of any character. For a query of "foo*bar", matches will include "foo123abcbar", "foobar", and "foo___123abcbar". To search for any match among several possible patterns, the values may be ORed together with the '|' character. For example, to search for "foo" OR "bar", pass in "query=foo|bar". This may be extended to an arbitrary number of values, such as "query=foo|bar|baz".

Similarly, the query can be used to specify that multiple patterns must be found across all fields specified in "query_fields" for a row to be returned. To specify that multiple patterns must be found, include a space between each one. For example, to search across fields where the fields must contain both "foo" AND "bar", provide "query=foo bar". Again, this may be used on an arbitrary number of patterns. To search for rows that contain all of "foo" AND "bar" AND "baz" within the fields specified, provide "query=foo bar baz".

It should be noted that it is possible for all of the matches to a query to appear in a single field. For example, if "query=foo bar", and a field queried contains "foo bar blah", it will be considered a match. Obviously the queries matches can also be spread across different fields.

The following data is used for the examples below:

Request: 'query_fields=color', 'query=red'

Response:

Explanation: The only row with a "color" column matching "red" is row 2.

Request: 'query_fields=id,number', 'query=3'

Response:

Explanation: Column "id" for row 3 matches the query, and column "number" for number for row 1 matches as well.

Request: 'query_fields=flavor', 'query=chocolate\|strawberry'

Response:

Explanation: This query returns rows containing chocolate and/or strawberry in the flavor column. Rows 1, 2, and 4 all contain matches. Row 4 actually matches both queries.

Request: 'query_fields=flavor', 'query=chocolate strawberry'

Response:

Explanation: This query returns rows containing chocolate AND strawberry in the flavor column. Only row 4 contains matches for both queries.

Request: 'query_fields=name,number', 'query=*3\|three'

Response:

Explanation: Searches across the name and number columns for a value either ending in '3', or containing "three". Row 1 contains 3 in the number field matching the first query, row 3 has a name of "widget3", matching the first query, and row 2 has a number containing three, matching the second query.

Request: 'query_fields=', 'query=1\|2\|3 th'

Response:

Explanation: Searches across all columns, looking for rows where a row both contains either 1 and/or 2 and/or 3, and contains a value starting with "th". Row 1 contains a value matching 1 or 2 or 3, but has no column that begins with th. Similarly, row 4 has a value beginning with "th", but does not contain 1 or 2 or 3. Therefore only rows 2 and 3 are returned, which match both queries.

ONTAP Error Response Codes

By default, calling GET on a collection generally returns only the properties that uniquely identify the record, along with a HAL 'self' link to the resource instance. However, you can choose the specific fields you want using the fields parameter. The fields parameter can also be used with GET when retrieving a single resource instance.

For discovery purposes, except for the CLI passthrough, the client can retrieve all standard properties using fields=*. These are the same properties returned when a GET is called on the specific instance using the path keys. However, using fields=\* is more expensive than selecting only the specific fields that are needed. In addition, because future releases may include additional properties in this list, or remove properties that were included by default, we strongly discourage using this in client-side software that is depending on specific fields being returned. To use the same list of fields when dealing with multiple versions of ONTAP, specify ignore_unknown_fields=true.

Some fields are more expensive to retrieve and are not included when using fields=* (or the instance-level GET). These fields are noted in the documentation. They can be returned either by specifying the fields directly, or by using fields=\*\*. However, we again strongly discourage this from being encoded into any client-side software. The performance of client software will suffer if a future version of ONTAP adds support for additional expensive properties.

The fields input parameter allows you to specify exactly which fields you want to be returned.

When an API contains fields that are objects, an entire object can be specified to return every field within the object. Individual fields within the object can be specified using dotted notation, as demonstrated below. Braces can be used to specify multiple fields within an object without repeating the object name. Braces can be nested within each other to select individual attributes within an object hierarchy.

Example fields query:

Several query parameters control the return of records.

The default setting for return_records is true for GET calls and false for all other methods. When false, the array of records is not returned.

The return_timeout parameter specifies the number of seconds the cluster spends performing an operation before returning. The allowed range is 0 to 120 seconds. If the timeout is reached, GET calls return the records collected along with a pagination link. Other methods return and complete asynchronously. See Non-blocking-operations for more details.

The default setting for return_timeout is 15 seconds for GET calls. For all other methods it is 0 seconds. This means that these calls might execute asynchronously in order to return as fast as possible.

The max_records parameter limits the number of records that are returned (or acted on) before providing the "next" pagination link.

The offset parameter determines how many records to skip over prior to returning the first record.

For example, if you have a total of 15 records, and specify an offset of 10, only records 11-15 inclusive will be returned. When combined with a query or sorting specification, the offset will apply after the query or sorting, meaning that you will get records beginning at the Nth record, taking into account the query and sort order. Note that the computational cost of skipping over N records is likely as great as actually returning those N records.

All calls to GET on a resource collection allow you to page through the results. If the max_records parameter is not specified, the cluster returns as many records as possible within the return_timeout time threshold. The number of records returned can be further limited by specifying a value for the max_records parameter. When the operation reaches either the return_timeout or the max_records threshold, it stops and returns the records as well as a HAL link that can be used to get the next page of records. It is possible for a pagination link to be returned even if there are no additional records. This occurs because the cluster does not check if there is an additional record before returning when it reaches a threshold. When there are potentially additional records, the response header will also contain a Link header containing the link followed by rel="next".

The following is an example of the "next" link, which returns with a collection of records:

The response to collection operations includes a num_records field. By passing return_records=false with a GET call, you can retrieve the number of records without returning the records themselves. However, if either the return_timeout or max_records threshold is reached, an incomplete or partial number of records is returned and the "next" link must be called to retrieve additional record counts. All the partial counts must be added together to calculate the total count.

By default, records in a collection are returned in the order defined by the object. You can change the order by specifying the order_by query parameter. Most uses of the order_by parameter collect and reorder all records in the collection. This can be expensive when the collection is large. Therefore, clients are discouraged from paginating through the results with max_records when using order_by.

If you want to sort on multiple fields (where the prior key value is the same), separate any fields (and optional direction) with a comma.

By default, sorting is done in ascending order based on the field type's ordering. If desc is specified after a field name, that field is sorted in descending order. Combining this with max_records allows you to see the top or bottom records based on the value of the specified field(s). When using this top or bottom functionality, queries on certain fields might require more time to search the entire collection regardless of the number of records actually returned.

Important Notes:

Every API call returns a top-level JSON object. These JSON objects includes GET calls that contain an array of records. This nesting technique allows metadata about the resource or resource collection to be returned as well as each resource instance.

GET calls that return an array of records can contain the following top-level elements:

Some APIs might include additional top-level elements. For example, some APIs may include a top-level errors array which can include errors if the array of records is incomplete (for reasons other than pagination). See the documentation for each API to check for custom top-level elements.

When an error occurs, an error object is returned in the response body. The error code is an integer returned in a JSON string. The optional target element is returned when ONTAP determines the error is due to a specific input field that you've supplied.

The following error codes can be returned by any ONTAP REST endpoint. Refer to individual endpoint documentation for additional endpoint specific error codes.

ONTAP Error Response Codes

POST, PATCH, or DELETE operations that can take more than 2 seconds are considered asynchronous operations. They are implemented as non-blocking operations. Any API call that is expected to return in less than 2 seconds is considered synchronous. Synchronous operations ignore the return_timeout parameter.

If the return_timeout is less than the time it takes for an operation to complete, the server returns the code 202 Accepted after waiting for the specified return_timeout seconds. The default return_timeout for non-blocking operations is 0 seconds, meaning the operation returns as fast as possible. However, the operation never returns the success code 200 OK, but instead returns either an error or the code 202 Accepted.

When a POST operation that is creating a resource returns 201 Created (synchronous) or 202 Accepted (asynchronous), the response header includes the Location of the resource. For asynchronous operations, a GET call on this resource link may return code 404 Not Found until the operation successfully completes. Use the returned job link instead of the Location link to determine when the asynchronous operation is complete. POST operations that return code 200 OK do not populate the Location header.

The following example shows how to send a POST request and retrieve the Location header in return. Here "readonly" privileges are added to "/api/cluster" for the "test" security role:

The Location Header provides the location of the resource that is newly created as a part of the POST request. %2Fapi%2Fcluster is the identifier for the new privilege in the example above.

Non-blocking or asynchronous operations are executed using jobs. The response to a non-blocking operation includes information about the job performing the operation, including a HAL link to the job resource. The job record also includes state and message fields. The message field indicates the progress of the operation while the state field indicates running. When a job is successful, the state and message fields indicate success. If an operation fails for any reason, the job's state reports error, and the message describes the problem that the operation encountered.

For POST operations, when a job is successfully completed, you can use the link from the Location header of the original response to retrieve the resource.

See GET /cluster/jobs

The following supported HTTP status codes are returned by ONTAP:

The ONTAP REST API supports the following HTTP methods:

Many objects contain properties related to various sizes. Examples can be found in the aggregate object, volume object, lun object and nvme_namespace object. These properties are documented as type integer.

Unless otherwise documented, all sizes are reported in GET in bytes.

Depending on the development language-specific code generation, the API typically also requires an integer value in bytes for POST and PATCH input as well.

Where a string value is accepted, such as query parameters and ad-hoc curl requests, any of the following suffixes can be used to specify different units:

SVM tunneling allows for the scoping of REST APIs to any SVM from the cluster admin SVM interface. The HTTP headers "X-Dot-SVM-Name" and/or "X-Dot-SVM-UUID" are an alternative to supplying svm.name and/or svm.uuid in the request query or body. This allows for setting a context for an HTTP connection and reusing it for multiple calls. The cluster management interface or node management interface can be used instead of the desired SVM's interface. When either SVM tunneling or the SVM interface are used, any svm.name and svm.uuid properties need not be supplied in the request body, even if they are documented as required in the API. If they are supplied and do not match the SVM specified by the tunneling headers, then a 400 error will be returned.

Creates a new volume on SVM "vs0":

Retrieves all volumes on SVM "vs0":

Deletes a volume on SVM "vs0" using the X-Dot-SVM-UUID header:

Retrieves all IP interfaces on SVM "vs3":

It may be useful for tools that use REST to categorize resources using tags for the purposes of tracking or grouping resources for certain purposes. For example, an application might want to create a set of resources for a certain project or group and set a tag on all of those resources that indicates which project or group they were created for. The API provides a standardized property in some APIs for doing so called _tags. This property begins with an underscore to indicate that it is a generic property that is used for the same purpose across many different APIs, much like the _links property is.

Retrieve a list of all volumes that were provisioned for the staging environment:

Tag a volume as belonging to the accounting group when the volume is created

Remove an existing tag while leaving the rest

Remove all tags

To help CLI and ONTAP users transition to the ONTAP REST API, ONTAP provides a private REST API endpoint that can be used to access any CLI command. Usage of this API call is recorded and returned in the AutoSupport data collection so that NetApp can identify usablity and functionality improvements in the REST API for future releases. There is no per-API documentation for the REST API access for each CLI command. Unlike the documented REST APIs, the API paths and properties for the CLI passthrough correspond very closely to the CLI. There are several rules that govern all the differences between a CLI command and the REST API mirroring the CLI command.

The API paths mirror the CLI paths, except for the use of the "show", "create", "modify", and "delete" verbs. Instead of using these four CLI verbs in the REST API, the corresponding HTTP methods must be used (GET, POST, PATCH, and DELETE). The four CLI verbs are removed from the API path supporting a command. For any commands where the last verb is hyphenated and begins with one of these verbs (for example, "show-space" or "delete-all"), you must remove the verb and following hyphen from the path. Any space in a full command path becomes a forward slash in the REST API (for example, "system node" becomes "/api/private/cli/system/node"). For non-show CLI commands that use non-standard verbs, the POST method should be used on the full path with the final verb in the API path. For example, "volume rehost" becomes "POST /api/private/cli/volume/rehost" and "cluster add-node" becomes "POST /api/private/cli/cluster/add-node".

To know which HTTP methods are supported for an API call, both documented and CLI-based, clients can use the "OPTIONS" HTTP method. For example, using OPTIONS on "/api/private/cli/volume" returns 'OK' with the HTTP "Allow" header containing a list of the supported HTTP methods (for example, "Allow: GET, HEAD, OPTIONS, POST, DELETE, PATCH"). For feature-specific CLI verbs, you can use OPTIONS on the API path. For example, using OPTIONS on "/api/private/cli/volume/restrict" returns with the HTTP header "Allow: OPTIONS, POST". Some of the CLI "show" commands do not contain the standard verb. For example, calling OPTIONS on "/api/private/cli/cluster/add-node-status" returns "Allow: GET, HEAD, OPTIONS".

There are some commands in the CLI that will not work using REST APIs. This includes most show commands that do not support "show -fields" in the CLI. The REST API also does not support CLI commands that create a new shell (like "run" and "vserver context").

Here are several examples of mappings from the ONTAP CLI to the ONTAP REST API for the /api/private/cli path:

All CLI parameters are supported in the CLI-based REST APIs. However, REST converts hyphens (-) in CLI parameter names to underscores (_) in the REST API JSON response body. In general, REST API responses use the same formatting for property values as ONTAPI. For example, enumerated values are formatted in lowercase instead of uppercase and with underscores instead of hyphens in the REST API response body. Both CLI and ONTAPI formats are allowed on input. Also similar to ONTAPI, sizes and percentages in REST are encoded as integers in bytes. Unlike ONTAPI or the CLI, date and time values in REST are encoded with the ISO-8601 format. All fields that you want returned from the GET call must be specified using the fields parameter. Note that the /api/private/cli/…​ APIs do not support "fields=*".

Retrieve OPTIONS for volumes endpoint (with results contained in header):

GET size and percent-used for all volumes:

GET size and percent-used for a specific volume:

POST a new volume with all required attributes:

Attempt to DELETE an online volume:

PATCH a volume to become offline:

DELETE the offline volume:

DELETE an offline volume without waiting:

As shown in the previous example, any non-field and non-error based output that would have appeared in the CLI is returned in a top-level cli_output attribute in the response body. This does not contain normal CLI headers or field values. It only displays messages that were printed to the CLI.

Error codes in the response body are mapped to the most appropriate HTTP status codes. In cases where this is not done, the HTTP status code defaults to 500. This does not necessarily indicate that the error is internal to ONTAP.

All CLI-based REST APIs are RBAC-controlled, based on the role of the authenticated user and have the same protections they have in the CLI.