We are introducing an experimental browser.app Web Extension API that would allow privileged add-ons to make changes to the Firefox app itself.

At the outset we plan to support three calls:

browser.app.checkUpdate

Checks for updates to Firefox.

browser.app.updateBrowser

Updates Firefox if an update is available. Equivalent to clicking the update item in the toolbar menu.

browser.app.resetBrowser

Refreshes Firefox.

based on Slack discussion, I assume this would be browser.experiments.app?

Yes, this the API we discussed on Slack with Shane.

Can we post the pertinent part of the slack conversation here? It's been so long I don't recall details, and it would be useful to have the context.

adw, mdeboer, and I approached you to ask about the best way to implement the three API calls in the bug description. You said:

I'd like to try an alternate approach with this, especially since the addition of the api seems pretty questionable. Implement this as an experimental api rather than building it into m-c. If you're concerned about breakage, land a test that includes the experimental api in m-c

adw and mdeboer thought about it and Drew posted:

Our conclusion was that we should follow Shane’s advice: We should use experimental APIs, not to the exclusion of landing APIs in mozilla-central, but as a part of our process. The long-term goal is to land good APIs in mozilla-central, but the way to achieve that maybe is not starting off with mozilla-central, as we have been doing.
You can envision a “graduation” process where APIs start as experimental APIs and are developed over the course of several experiments. So the first experiment would have version 1.0 of an API, and then the Nth experiment would have version N.0 with the API relatively stable and improved enough to accommodate a wider range of use cases. The API would remain experimental the whole time.
After the Nth experiment, we might look back and feel confident that the API can now meet the needs of a wide range of extensions, so at that point we might land it in mozilla-central. Looking ahead even further, you can imagine the API “graduating” from a webext API to an internal urlbar API so that internal parts of Firefox could use it. (And then the webext implementation would become a really thin wrapper around it, presumably.)
And maybe an API never becomes useful to more than one or two experiments. Then it just stays an experimental API. And it might be obvious in advance that an API probably is useful only to a particular experiment.
There are some logistical issues to work out, like tests as Shane mentions. I guess we’d have a repo somewhere where we’d maintain our set of experimental APIs (similar to the old Shield utils). There’s the review process -- who needs to review what, what teams need to be involved.

You answered some follow-up questions we had, stressed that the experiment APIs should still be reviewed by someone on the WebExt team, and finally you said

it will be in an experimental namespace

my preference would be what crashme does. https://github.com/rhelmer/webext-experiment-crashme/blob/master/experiments/crash/schema.json

so you would have browser.experiments.urlbar or such

This is being done in bug 1568595, where we're adding a browser.urlbarExperiments namespace. I'll mark this fixed when that bug is marked fixed. That bug is a nudges bug, and it's about adding a specific function, but it sets up schema and implementation files plus a way to test the API, which is really all I had in mind for this bug. I think we should use the urlbarExperiments namespace for the functions mentioned in comment 0 and any other APIs we need for urlbar experiments, and we can track those functions in their respective bugs.

The latest patch in bug 1568595 uses browser.experiments.urlbar.

Bug 1568595 is fixed, marking this fixed.