Chrome exposes special capabilities to Extensions and Platform Apps through different APIs. The core API system is shared between Extensions and Platform Apps; APIs are defined and exposed in the same fashion for both.
Before implementing a new API, it has to go through an approval process. This approval process helps ensure that the API is well defined, does not introduce any privacy, security, or performance concerns, and fits in with the overall product vision.
Default: Public
Extension and App APIs can either be public (available for any extension or app to potentially use, though frequently there are other constraints like requiring a permission) or private (only available to extensions or apps with a specific whitelisted ID). In general, private APIs should only be used for pieces of functionality internal to Chromium/Chrome itself (e.g., the translation utility, printing, etc). Public APIs should always be the default, in order to foster openness and innovation.
Good reasons for a private API might be:
Bad reasons for a private API might be:
The API is only needed for a Google property (other than Chrome/Chromium). In the spirit of openness, we should, when possible, provide people with the means to build alternatives. Just because something is needed by a Google property does not mean it wouldn’t be useful to a third-party.
The API is needed by a Google property (other than Chrome/Chromium), and is too powerful to expose to any third-party extension or app. Generally, if an API is too powerful to expose to a third-party extension, we don’t want to expose it to any kind of (non-component) extension, as it increases Chrome’s attack surface. Typically, these security concerns can be addressed by finding alternative or tweaking the API surface.
This is just a quick-and-dirty API and we don’t want to go through a long process. Quick-and-dirty hacks have a nasty habit of staying around for years, and often carry with them their own maintenance burdens. It’s very frequently cheaper to design an API well and have it be stable than to have a quick solution that has to be constantly fixed.
Unless there is a compelling reason to make an API private, it should default to public.
In general, you (or rather, your team) will own the API you create. The Extensions and Apps teams do not own every API, nor would it be possible for those teams to maintain them all. This means that your team will be responsible for maintaining the API going forward.
Extensions Default: All Desktop Platforms Extensions are supported on all desktop platforms (Windows, Mac, Linux, and ChromeOS). By default, an extension API will be exposed on all these platforms, but this can be configured to only be exposed on a subset. However, an API should only be restricted if there is strong reason to do so; otherwise, platforms should have parity.
Platform Apps: ChromeOS Only Platform apps are deprecated on all platforms except ChromeOS.
Platform apps have been deprecated on all platforms except ChromeOS. We are not actively expanding the Chrome Apps platform significantly.
Starting the review process early is encouraged, and if some of the artifacts are missing or in progress, we’re happy to work with you on it. It’s better to have us review the API in principle to ensure it’s something we’re comfortable adding to the platform, and then work out the details, than to invest heavily only to find out that we don’t want to add the API to the platform. Feel free to file a bug without everything ready, or to email extension-api-reviews@chromium.org for advice and feedback!
In order to propose a new API, file a new bug with the appropriate template, and fill in the required information. This should include:
API Namespace: The namespace of your API. This is how your API will be exposed in JS. For instance, the chrome.tabs API has the ‘tabs’ namespace.
Target Milestone: The target milestone for releasing this API. It’s okay for this to be a rough estimate.
API OWNERS: Usually, you will be responsible for ownership of the API. List appropriate usernames, team aliases, etc.
API Overview Doc: A link to your completed API Overview document.
Design Doc(s): Any additional design docs. Depending on the complexity of the API, this might not be necessary with the API Overview doc above.
Supplementary Resources (optional): Any additional resources related to this API. For instance, if this API is part of a larger feature, any PRDs, docs, mocks, etc for that feature can be linked here (or through an associated crbug.com issue).
Note: This process does not eliminate the need for a larger design review, if one would otherwise be required. See go/chrome-dd-review-process for guidance (sorry, internal only. If this is a large feature, we recommend finding a member of the chrome team to help you drive it and own it). However, it should be possible to get feedback from many of the required parties during that review process, which would expedite the additional approvals needed.
Please email the proposal to extension-api-reviews@chromium.org for any additional feedback.
All APIs, public or private, will need sign off from a few different parties:
API Review: The overall review of the API, including comments on exposed methods, events, or properties, and an overall review for whether the API fits in with the overall product vision. This sign off will come from a member of the Extensions or Apps team.
Security Review: A review to ensure that the API will not pose any unnecessary security risk.
Privacy Review: A review to ensure that there are no privacy concerns around leaking user data without permission.
UI Review: A review of any UI implemented as part of your API. This review may not be necessary if there is no UI element to your API.
Modifications to an existing API should go through a similar process. Since modifications to these APIs are frequently far-reaching, please do not skip the proposal process! However, you may be able to expedite it. In particular, small changes (like adding a new property to a method) do not need a design doc or API Overview doc. Larger changes, like adding multiple new methods and events, should still include an API Overview (though it can be brief). Medium-sized changes, like adding a single new method, are up to the discretion of the API reviewers - we may ask for an API Overview, but it might not be necessary.
Do I need an API review for a private API? Yes! Private APIs are not as scrutinized as public APIs because we don't need to be as worried about API ergonomics, and we can be a little more lenient in security. However, we still need to review the API to make sure that:
Who signs off for the API review? The API review bit will be flipped by either an extensions or apps team member. If your API has been languishing, please ping rdevlin.cronin@ (Extensions APIs) or benwells@ (Apps APIs).
Note: All these templates default to public visibility.