REST Strategy¶

Status ¶

Accepted

Context¶

ONTAP has published a customer product communiqué (CPC-00410) announcing that ZAPIs will reach end of availability (EOA) in ONTAP 9.13.1 released Q2 2023.

This document describes how Harvest handles the ONTAP transition from ZAPI to REST. In most cases, no action is required on your part.

Harvest API Transition¶

By default, Harvest will use ZAPIs until ONTAP version 9.12.1. Beginning with ONTAP 9.12.1 and after, Harvest will default to REST.

Harvest includes a full set of REST templates that export identical metrics as the included ZAPI templates. No changes to dashboards or downstream metric-consumers will be required. See below if you have added metrics to the Harvest out-of-the-box templates.

Read on if you want to know how you can use REST sooner, or you want to take advantage of REST-only features in ONTAP.

Frequently Asked Questions¶

How does Harvest decide whether to use REST or ZAPI APIs?¶

Harvest asks the cluster for its ONTAP version:

If the version is earlier than 9.12.1, Harvest will use the collector(s) defined in your harvest.yml.
If the version is 9.12.1 or later, Harvest will use REST, unless the HARVEST_NO_COLLECTOR_UPGRADE environment variable is set or the prefer_zapi poller option is true. When the environment variable or prefer_zapi option are set, Harvest will use ZAPIs unless the cluster no longer talks ZAPI.

graph TD
A(Harvest asks the cluster<br>for its ONTAP version) --> B(Version before<br>9.12.X?)
A --> C(9.12.X)
A --> D(9.13.X)

B --> AA{Does your harvest.yml<br>specify a REST collector?}
AA -->|No| F(Use ZAPI) 
AA -->|Yes|G(Use REST)

C --> CC{Is HARVEST_NO_COLLECTOR_UPGRADE<br>environment variable set?<br><br>Or is the prefer_zapi poller option setset?}
CC --> |No| G
CC --> |Yes|CZ(Use ZAPI) 

D --> X(Use REST)

Why would I switch to REST before `9.13.1`?¶

You have advanced use cases to validate before ONTAP removes ZAPIs in 9.13.1
You want to take advantage of new ONTAP features that are only available via REST (e.g. cloud features, event remediation's, name services, cluster peers, etc.)
You want to collect a metric that is not available via ZAPI
You want to collect a metric from the ONTAP CLI. The REST API includes a private CLI pass-through to access any ONTAP CLI command

Can I start using REST before `9.13.1`?¶

Yes. Several customers already are. Be aware of the following limitations:

Harvest collects config counters via REST by enabling the Rest collector in your harvest.yml, but ONTAP did not include performance counters via REST until 9.11.1. That means Harvest's RestPerf collector won't work until 9.11.1. ONTAP supports a subset of performance counters in 9.11.1. The full set is available in 9.12.1.
There may be performance metrics missing from versions of ONTAP earlier than 9.11.1.

A counter is missing from REST. What do I do?¶

The Harvest team has ensured that all the out-of-the-box ZAPI templates have matching REST templates with the same metrics. Any additional counters you have added may be missing in REST.

Join the Harvest discord channel and ask us about the counter. Sometimes we may know which release the missing counter is coming in, otherwise we can point you to the ONTAP process to request new counters.

Can I use the REST and ZAPI collectors at the same time?¶

Yes. Harvest ensures that duplicate resources are not collected from both collectors.

When there is potential duplication, Harvest first resolves the conflict in the order collectors are defined in your poller and then negotiates with the cluster on the most appropriate API to use per above.

Let's take a look at a few examples using the following poller definition:

cluster-1:
    datacenter: dc-1
    addr: 10.1.1.1
    collectors:
        - Zapi
        - Rest

When cluster-1 is running ONTAP 9.9.X (ONTAP still supports ZAPIs), the Zapi collector will be used since it is listed first in the list of collectors. When collecting a REST-only resource like, nfs_client, the Rest collector will be used since nfs_client objects are only available via REST.
When cluster-1 is running ONTAP 9.12.1 (ONTAP still supports ZAPIs), the Rest collector will be used since Harvest automatically uses REST for clusters at 9.12.1 or later.
When cluster-1 is running ONTAP 9.12.1 (ONTAP still supports ZAPIs) and the environment variable HARVEST_NO_COLLECTOR_UPGRADE is set, the Zapi collector will be used because of the included environment variable.
When cluster-1 is running ONTAP 9.15.1 (ONTAP removed ZAPIs) and the environment variable HARVEST_NO_COLLECTOR_UPGRADE is set, the Rest collector will be used since Harvest asks the cluster if it speaks ZAPI and the cluster answers no.

If you want the REST collector to be preferred over the ZAPI one, change the order in the collectors section so Rest comes before Zapi.

If the resource does not exist for the first collector, the next collector will be tried. For example, when collecting VolumeAnalytics resources, the Zapi collector will not run because VolumeAnalytics objects are only available via REST.

I've added counters to existing ZAPI templates. Will those counters work in REST?¶

ZAPI config metrics often have a REST equivalent that can be found in ONTAP's ONTAPI to REST mapping document.

ZAPI performance metrics may be missing in REST. If you have added new metrics or templates to the ZAPIPerf collector, those metrics likely aren't available via REST. You can check if the performance counter is available or ask the Harvest team on Discord.

I'm using ONTAP version 9.12.X, but I want to continue using ZAPIs. How do I do that?¶

There are two options:

Set the environment variable HARVEST_NO_COLLECTOR_UPGRADE=1 and Harvest will not upgrade your collector from ZAPI to REST.
Edit your harvest.yml config file and add the prefer_zapi option to the poller section. See configure Harvest for details.

Reference¶

Table of ONTAP versions, dates and API notes.

ONTAP version	Release Date	ONTAP Notes
`9.11.1`	Q2 2022	First version with REST performance metrics
`9.12.1`	Q4 2022	ZAPIs still supported - REST performance metrics have parity with Harvest collected ZAPI performance metrics
`9.13.1`	Q2 2023	ZAPIs removed. REST only release - REST config and performance parity with ZAPIs