Which version of the Excel API should be referenced in the manifest file, when submitting add-in for the Office Store?

Question

When submitting Excel add-in to the office store. Which version of the Excel API should be referenced in the manifest file?

We have experienced being rejected because we didn’t refer to the newest version of the Excel API. But if our Excel add-in supports an older version of the API. Shouldn't we be referencing this?

Answer 1

There are several aspects to the versioning of the Office.js library.

First, there is versioning of the actual JavaScript source files. Fortunately, this part is pretty simple: you always want the latest and greatest of the production Office.js, which is conveniently obtainable through our CDN: https://appsforoffice.microsoft.com/lib/1/hosted/Office.js. The files are also shipped as a NuGet package to allow corporate firewalled development, but the NuGet may lag a few weeks behind the CDN -- and in any case, any Store-bound add-in is required to reference the CDN location. So, in terms of Office.js versions, there isn't really versioing there: there is simply the one and only evergreen, frequently-updated, always-back-compatible, Store-required CDN version.

(While on the subject of CDNs: we also have a beta CDN, available at https://appsforoffice.microsoft.com/lib/beta/hosted/Office.js. This one is great to testing newly implemented-but-not-yet-officially-stamped-as-done features, which you'll find in our Open Specs: http://dev.office.com/reference/add-ins/openspec. However, any new APIs therein should be considered as strictly "beta", and they may well be renamed, re-grouped, or postoponed -- so your app should not rely on them, as we explicitly reserve the right to break pack-compat on the beta branch. An API is not "done" until it is listed in IntelliSense ande Documentation as complete, until it's available on the Production CDN, *and until its isSetSupported returns true -- more on that momentarily).

The more interesting bit for versioning are the actual API capabilities that are offered by each host. The Office.js library will have the latest JS code to be able to run them, but older hosts might not be able to support some of the functionality. For example, if you look at https://dev.office.com/reference/add-ins/requirement-sets/excel-api-requirement-sets, you will see that the 2016 wave of Excel APIs -- grouped under the "ExcelApi" requirement set -- has had three versions to date: 1.1, 1.2, and 1.3. ExcelApi 1.1 was what shipped with Office 2016 RTM in September 2015; 1.2 shipped in early March 2016; and 1.3 shipped just recently, and is in the process of being rolled out to the CDN. Each API set version has a corresponding Office host version that supports this API set (for most APIs, there have to be both JS and host-side changes; it's fairly rare that something can be a purely-JS addition). The version numbers are listed in the table, and there are links below the table to find a mapping from build numbers to dates.

Each of the API set versions contain a number of fairly large features, as well as incremental improvements to existing features. The topic for each requirment set, such as the link above, will provide a detailed listing of each of those features. And as you're programming, if you are using the JavaScript or TypeScript IntelliSense, you should be able to see the API versions for each of your APIs displayed as part of the IntelliSense:

You can use the requirement set in one of two ways. You can declare in the manifest that "I need API set ExcelApi 1.2, or else my add-in doesn't work at all" -- and that's fine, but then of course you aren't able to service older hosts, and so your add-in won't even show up there. Alternatively, if you add-in could sorta work in a 1.1 environment, but you want to light-up additional functionality on newer hosts that support it, you can use the manifest to declare only your minimal API sets that you need (e.g., ExcelApi 1.1), and then do runtime checks for higher version numbers via the isSetSupported API. Neat ways to get environment (i.e. Office version) has a very detailed explanation of this isSetSupported API-checking.

Hope this helps!