Input variables controlling an API request

HTTP methods​

The HTTP methods supported by the ONTAP REST API are shown in the following table.

Request headers​

You must include several headers in the HTTP request.

Content-type

If the request body includes JSON, this header must be set to application/json.

Accept

This header should be set to application/hal+json. If it is instead set to application/json none of the HAL links will be returned except a link needed to retrieve the next batch of records. If the header is anything else aside from these two values, the default value of the content-type header in the response will be application/hal+json.

Authorization

Basic authentication must be set with the user name and password encoded as a base64 string.

Request body​

The content of the request body varies depending on the specific call. The HTTP request body consists of one of the following:

• JSON object with input variables

• Empty

Filtering objects​

When issuing an API call that uses GET, you can limit or filter the returned objects based on any attribute. For example, you can specify an exact value to match:

In addition to an exact match, other operators are available to return a set of objects over a range of values. The ONTAP REST API supports the filtering operators shown in the table below.

You can also return a collection of objects based on whether a specific field is set or not set by using the null keyword or its negation !null as part of the query.

Requesting specific object fields​

By default, issuing an API call using GET returns only the attributes that uniquely identify the object or objects, along with a HAL self link. This minimum set of fields acts as a key for each object and varies based on the object type. You can select additional object properties using the fields query parameter in the following ways:

• Common or standard fields

  Specify fields=* to retrieve the most commonly used object fields. These fields are typically maintained in local server memory or require little processing to access. These are the same properties returned for an object after using GET with a URL path key (UUID).

• All fields

  Specify fields=** to retrieve all the object fields, including those requiring additional server processing to access.

• Custom field selection

  Use fields=<field_name> to specify the exact field you want. When requesting multiple fields, the values must be separated using commas without spaces.

Sorting objects in the output set​

The records in a resource collection are returned in the default order defined by the object. You can change the order using the order_by query parameter with the field name and sort direction as follows:

For example, you can sort the type field in descending order followed by id in ascending order:

Note the following:

• If you specify a sort field but don’t provide a direction, the values are sorted in ascending order.

• When including multiple parameters, you must separate the fields with a comma.

Pagination when retrieving objects in a collection​

When issuing an API call using GET to access a collection of objects of the same type, ONTAP attempts to return as many objects as possible based on two constraints. You can control each of these constraints using additional query parameters on the request. The first constraint reached for a specific GET request terminates the request and therefore limits the number of records returned.

Limiting the number of objects

By default, ONTAP returns a maximum of 10,000 objects for a GET request. You can change this limit using the max_records query parameter. For example:

max_records=20

The number of objects actually returned can be less than the maximum in effect, based on the related time constraint as well as the total number of objects in the system.

Limiting the time used to retrieve the objects

By default, ONTAP returns as many objects as possible within the time allowed for the GET request. The default timeout is 15 seconds. You can change this limit using the return_timeout query parameter. For example:

return_timeout=5

The number of objects actually returned can be less than the maximum in effect, based on the related constraint on the number of objects as well as the total number of objects in the system.

Narrowing the result set

If needed, you can combine these two parameters with additional query parameters to narrow the result set. For example, the following returns up to 10 ems events generated after the specified time:

time=> 2020–11–11T15:41:29.140265Z&max_records=10

You can issue multiple requests to page through the objects. Each subsequent API call should use a new time value based on the latest event in the last result set.

Size properties​

The input values used with some API calls as well as certain query parameters are numeric. Rather than provide an integer in bytes, you can optionally use a suffix as shown in the following table.