Skip to main content
ONTAP tools for VMware vSphere 10.2

Get started with the REST API

Contributors netapp-jani
PDFs

You can quickly get started using ONTAP tools for VMware vSphere REST API. Accessing the API provides some perspective before you begin using it with the more complex workflow processes on a live setup.

Hello World

You can run a simple command on your system to get started using ONTAP tools for VMware vSphere REST API and confirm its availability.

Before you begin

  • Ensure that the Curl utility is available on your system.

  • IP address or host name of ONTAP tools for VMware vSphere server

  • Username and password for an account with authority to access ONTAP tools for VMware vSphere REST API.

Note If your credentials include special characters, you need to format them in a way that is acceptable to Curl based on the shell you are using. For example, you can insert a backslash before each special character or wrap the entire username:password string in single quotes.
Step

At the command line interface, run the following to retrieve the plug-in information:

curl -X GET -u username:password -k "https://<ip_address>/api/hosts?fields=IncludePluginInfo"

Example:

curl -X GET -u admin:password -k "'https://10.225.87.97/api/hosts?fields=IncludePluginInfo"

How to access ONTAP tools for VMware vSphere REST API

You can access the ONTAP REST API in several different ways.

Network considerations

You can connect to the REST API through the following interfaces:

  • Cluster management LIF

  • Node management LIF

  • SVM management LIF

The LIF you choose to use should be configured to support the HTTPS management protocol. Also, the firewall configuration in your network should allow the HTTPS traffic.

Note You should always use a cluster management LIF. This will load balance the API requests across all the nodes and avoid nodes that are offline or experiencing connectivity issues. If you have multiple cluster management LIFs configured, they are all equivalent regarding access to the REST API.

Input variables controlling an API request

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 ONTAP tools for VMware vSphere REST API are shown in the following table.

Note Not all the HTTP methods are available at each of the REST endpoints.
HTTP method Description

GET

Retrieves object properties on a resource instance or collection.

POST

Creates a new resource instance based on the supplied input.

DELETE

Deletes an existing resource instance.

PUT

Modifies an existing resource instance.

Request headers

You should include several headers in the HTTP request.

Content-type

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

Accept

This header should be set to application/json.

Authorization

Basic authentication should be set with the username 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:

<field>=<query value>

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

Operator Description

=

Equal to

<

Less than

>

Greater than

⇐

Less than or equal to

>=

Greater than or equal to

UPDATE

Or

!

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.

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

Requesting specific object fields

By default, issuing an API call using GET returns only the attributes that uniquely identify the object or objects. 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 should be separated using commas without spaces.

Important 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

  • If you specify a sort field but do not provide a direction, the values are sorted in ascending order.

  • When including multiple parameters, you should 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 tools for VMware vSphere 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 tools for VMware vSphere 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 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 tools for VMware vSphere 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 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 byes) or tebibytes

PB

PB Petabytes (TB x 1024 byes) or pebibytes