docs: explain what to do if ZAPI metrics are missing in REST

docs/architecture/rest-strategy.md

@@ -9,28 +9,47 @@ In Progress
 ONTAP has published a customer product communiqué [(CPC-00410)](https://mysupport.netapp.com/info/communications/ECMLP2880232.html?access=a)
 announcing that ZAPIs will reach end of availability (EOA) in ONTAP `9.13.1` released Q2 2023.
 
-This document describes how Harvest is making the ONTAP transition, from ZAPI to REST, seamless for Harvest customers.
+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 up 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.
+No changes to dashboards or downstream metric-consumers will be required. 
+See [below](#ive-added-counters-to-existing-zapi-templates-will-those-counters-work-in-rest) 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 picks the appropriate API based on the following rules:
+Harvest asks the cluster for its ONTAP version:
 
-1. If you specify a particular collector in your `harvest.yml`, Harvest will use it.
-2. Otherwise, Harvest will ask the cluster if it supports ZAPIs.
-If the cluster says yes, Harvest will use ZAPIs, otherwise it will use REST. 
+* 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`, Harvest will use REST, unless you set the [no-upgrade environment variable](#im-using-ontap-version-912x-but-i-want-to-continue-using-zapis-how-do-i-do-that).
+* If the version is `9.13.1` or later, Harvest will use REST, because ZAPI has been removed.
 
+```mermaid
+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 NO_UPGRADE<br>environment<br>variable set?}
+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`
@@ -47,7 +66,7 @@ Yes. Several customers already are. There are a few caveats to be aware of:
    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`.
 
-2. It's better to publish a set of metrics once instead of multiple times. In other words, it does not make sense to
+2. It's preferable to publish a set of metrics once, instead of multiple times. Typically, you do not want to
    enable both the `Zapi` and `Rest` collector for an overlapping set of objects on the same cluster.
    It will work, but you'll put more load on the cluster and push duplicate metrics to Prometheus. 
    See [below](#can-i-use-the-rest-and-zapi-collectors-at-the-same-time) for details on how to use both collectors at the same time. 
@@ -56,7 +75,7 @@ Yes. Several customers already are. There are a few caveats to be aware of:
 
 ### A counter is missing from REST. What do I do?
 
-The Harvest team has ensured that all of the out-of-the-box ZAPI templates have matching REST templates with the same metrics.
+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](https://github.com/NetApp/harvest/blob/main/SUPPORT.md#getting-help) and ask us about the counter.
@@ -75,6 +94,19 @@ Typically, you will use ZAPI collectors with the out-of-the-box templates and ad
 For example, if you want to [collect controller RAM status](https://github.com/NetApp/harvest/discussions/1187) you must use the REST collector,
 since there is no ZAPI that returns that metric.
 
+### 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](https://library.netapp.com/ecm/ecm_download_file/ECMLP2882104).
+
+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](https://docs.netapp.com/us-en/ontap-automation/migrate/performance-counters.html#discover-the-available-performance-counter-tables) 
+or [ask the Harvest team on Discord](#a-counter-is-missing-from-rest-what-do-i-do).
+
+### I'm using ONTAP version 9.12.X, but I want to continue using ZAPIs. How do I do that?
+
+Set the environment variable `HARVEST_NO_COLLECTOR_UPGRADE=1` and Harvest will not 
+upgrade your collector from ZAPI to REST.
+
 ## Reference
 
 Table of ONTAP versions, dates and API notes.