Skip to main content
ONTAP Automation

Input variables controlling an API request

Contributors dmp-netapp
PDFs

You can control how an API call is processed through parameters and variables set in the HTTP request.

HTTP methods

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

Note Not all the HTTP methods are available at each of the REST endpoints. Also, both PATCH and DELETE can be used on a collection. See Object references and access for more information.
HTTP method Description

GET

Retrieves object properties on a resource instance or collection.

POST

Creates a new resource instance based on the supplied input.

PATCH

Updates an existing resource instance based on the supplied input.

DELETE

Deletes an existing resource instance.

HEAD

Effectively issues a GET request but only returns the HTTP headers.

OPTIONS

Determine what HTTP methods are supported at a specific endpoint.

Path variables

The endpoint path used with each REST API call can include various identifiers. Each ID corresponds to a specific resource instance. Examples include cluster ID and SVM ID.

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. For example:

Authorization: Basic YWRtaW46cGV0ZXJzb24=.

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 JSON object

Filtering objects

When issuing an API call with the GET method, you can limit or filter the returned objects based on any attribute using a query parameter.

Parsing and interpreting query parameters

A set of one or more parameters can be appended to the URL string beginning after the ? character. If more than one parameter is provided, the query parameters are split based on the & character. Each key and value in the parameter are split at the = character.

For example, you can specify an exact value to match using the equal sign:

<field>=<value>

For a more complex query, the additional operator is placed after the equal sign. For example, to select the set of objects based on a specific field that is greater than or equal to some value, the query would be:

<field>=>=<value>

Filtering operators

In addition to the examples provided above, additional operators are available to return objects over a range of values. A summary of the filtering operators supported by the ONTAP REST API is shown in the table below.

Note Any fields that are not set are generally excluded from matching queries.

Operator

Description

=

Equal to

<

Less than

>

Greater than

<=

Less than or equal to

>=

Greater than or equal to

!

Not equal to

*

Greedy wildcard

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.

Workflow examples

Some examples are included below from the REST API workflows at this site.

  • List disks

    Filter based on the state variable to select the spare disks.

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.

    Tip As a best practice, you should always identify the specific fields you want. You should only retrieve the set of common fields or all fields when needed. Which fields are classified as common, and returned using fields=*, is determined by NetApp based on internal performance analysis. The classification of a field might change in future releases.

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:

order_by=<field name> asc|desc

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

order_by=type desc, id asc

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.

Note If a request ends before iterating over all the objects, the response contains the link needed to retrieve the next batch of records.
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=> 2018-04-04T15: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.

Suffix Description

KB

KB Kilobytes (1024 bytes) or kibibytes

MB

MB Megabytes (KB x 1024 bytes) or mebibytes

GB

GB Gigabytes (MB x 1024 bytes) or gibibytes

TB

TB Terabytes (GB x 1024 bytes) or tebibytes

PB

PB Petabytes (TB x 1024 bytes) or pebibytes
Related information