Basic operational characteristics
While REST establishes a common set of technologies and best practices, the details of each API can vary based on the design choices.
Request and response API transaction
Every REST API call is performed as an HTTP request to the ONTAP system which generates an associated response to the client. This request/response pair is considered an API transaction. Before using the API, you should be familiar with the input variables available to control a request and the contents of the response output.
Support for CRUD operations
Each of the resources available through the ONTAP REST API is accessed based on the CRUD model:
For some of the resources, only a subset of the operations is supported. You should review the ONTAP API documentation page at your ONTAP cluster for more information about each resource.
Each resource instance or object is assigned a unique identifier when it is created. In most cases, the identifier is a 128-bit UUID. These identifiers are globally unique within a specific ONTAP cluster. After issuing an API call that creates a new object instance, a URL with the associated id value is returned to the caller in the location header of the HTTP response. You can extract the identifier and use it on subsequent calls when referring to the resource instance.
|The content and internal structure of the object identifiers can change at any time. You should only use the identifiers on the applicable API calls as needed when referring to the associated objects.|
Object instances and collections
Depending on the resource path and HTTP method, an API call can apply to a specific object instance or a collection of objects.
Synchronous and asynchronous operations
There are two ways that ONTAP performs an HTTP request received from a client.
- Synchronous processing
ONTAP performs the request immediately and responds with an HTTP status code of 200 or 201 if it is successful.
Every request using the methods GET, HEAD, and OPTIONS is always performed synchronously. In addition, requests that use POST, PATCH, and DELETE are designed to run synchronously if they are expected to complete in less than two seconds.
- Asynchronous processing
If an asynchronous request is valid, ONTAP creates a background task to process the request and a job object to anchor the task. The 202 HTTP status is returned to the caller along with the job object. To determine final success or failure, you must retrieve the state of the job.
Requests that use the methods POST, PATCH, and DELETE are designed to run asynchronously if they are expected to take more than two seconds to complete.
return_timeoutquery parameter is available with asynchronous API calls and can convert an asynchronous call to complete synchronously. Refer to
How asynchronous processing works using the Job objectfor more information.
The security provided with the REST API is based primarily on the existing security features available with ONTAP. The following security is used by the API:
Transport Layer Security
All traffic sent over the network between the ONTAP LIF and client is typically encrypted using TLS, based on the ONTAP configuration settings.
The same authentication options available with ONTAP System Manager and the Network Manageability SDK can also be used with the ONTAP REST API.
At an HTTP level, basic authentication is used for the API transactions. An HTTP header with the user name and password in a base64 string is added to each request.
ONTAP implements a role-based authorization model. The account you use when accessing the ONTAP REST API or API documentation page should have the proper authority.