path: root/toolkit/components/extensions/docs/basics.rst

.. _basics:

API Implementation Basics
=========================
This page describes some of the pieces involved when creating
WebExtensions APIs.  Detailed documentation about how these pieces work
together to build specific features is in the next section.

The API Schema
--------------
As described previously, a WebExtension runs in a sandboxed environment
but the implementation of a WebExtensions API runs with full chrome
privileges.  API implementations do not directly interact with
extensions' Javascript environments, that is handled by the WebExtensions
framework.  Each API includes a schema that describes all the functions,
events, and other properties that the API might inject into an
extension's Javascript environment.
Among other things, the schema specifies the namespace into which
an API should be injected, what permissions (if any) are required to
use it, and in which contexts (e.g., extension pages, content scripts, etc)
it should be available.  The WebExtensions framework reads this schema
and takes care of injecting the right objects into each extension
Javascript environment.

API schemas are written in JSON and are based on
`JSON Schema <http://json-schema.org/>`_ with some extensions to describe
API functions and events.
The next section describes the format of the schema in detail.

The ExtensionAPI class
----------------------
Every WebExtensions API is represented by an instance of the Javascript
`ExtensionAPI <reference.html#extensionapi-class>`_ class.
An instance of its API class is created every time an extension that has
access to the API is enabled.  Instances of this class contain the
implementations of functions and events that are exposed to extensions,
and they also contain code for handling manifest keys as well as other
part of the extension lifecycle (e.g., updates, uninstalls, etc.)
The details of this class are covered in a subsequent section, for now the
important point is that this class contains all the actual code that
backs a particular WebExtensions API.

Built-in versus Experimental APIs
---------------------------------
A WebExtensions API can be built directly into the browser or it can be
contained in a special type of extension called a privileged extension
that defines a WebExtensions Experiment (i.e. experimental APIs).
The API schema and the ExtensionAPI class are written in the same way
regardless of how the API will be delivered, the rest of this section
explains how to package a new API using these methods.

Adding a built-in API
---------------------
Built-in WebExtensions APIs are loaded lazily.  That is, the schema and
accompanying code are not actually loaded and interpreted until an
extension that uses the API is activated.
To actually register the API with the WebExtensions framework, an entry
must be added to the list of WebExtensions modules in one of the following
files:

- ``toolkit/components/extensions/ext-toolkit.json``
- ``browser/components/extensions/ext-browser.json``
- ``mobile/android/components/extensions/ext-android.json``

Here is a sample fragment for a new API:

.. code-block:: js

    "myapi": {
      "schema": "chrome://extensions/content/schemas/myapi.json",
      "url": "chrome://extensions/content/ext-myapi.js",
      "paths": [
        ["myapi"],
        ["anothernamespace", "subproperty"]
      ],
      "scopes": ["addon_parent"],
      "permissions": ["myapi"],
      "manifest": ["myapi_key"],
      "events": ["update", "uninstall"]
    }

The ``schema`` and ``url`` properties are simply URLs for the API schema
and the code implementing the API.  The ``chrome:`` URLs in the example above
are typically created by adding entries to ``jar.mn`` in the mozilla-central
directory where the API implementation is kept.  The standard locations for
API implementations are:

- ``toolkit/components/extensions``: This is where APIs that work in both
  the desktop and mobile versions of Firefox (as well as potentially any
  other applications built on Gecko) should go
- ``browser/components/extensions``: APIs that are only supported on
  Firefox for the desktop.
- ``mobile/android/components/extensions``: APIs that are only supported
  on Firefox for Android.

Within the appropriate extensions directory, the convention is that the
API schema is in a file called ``schemas/name.json`` (where *name* is
the name of the API, typically the same as its namespace if it has
Javascript visible features).  The code for the ExtensionAPI class is put
in a file called ``ext-name.js``.  If the API has code that runs in a
child process, that is conventionally put in a file called ``ext-c-name.js``.

The remaining properties specify when an API should be loaded.
The ``paths``, ``scopes``, and ``permissions`` properties together
cause an API to be loaded when Javascript code in an extension references
something beneath the ``browser`` global object that is part of the API.
The ``paths`` property is an array of paths where each individual path is
also an array of property names.  In the example above, the sample API will
be loaded if an extension references either ``browser.myapi`` or
``browser.anothernamespace.subproperty``.

A reference to a property beneath ``browser`` only causes the API to be
loaded if it occurs within a scope listed in the ``scopes`` property.
A scope corresponds to the combination of a Javascript environment
(e.g., extension pages, content scripts, etc) and the process in which the
API code should run (which is either the main/parent process, or a
content/child process).
Valid ``scopes`` are:

- ``"addon_parent"``, ``"addon_child``: Extension pages

- ``"content_parent"``, ``"content_child``: Content scripts

- ``"devtools_parent"``, ``"devtools_child"``: Devtools pages

The distinction between the ``_parent`` and ``_child`` scopes will be
explained in further detail in following sections.

A reference to a property only causes the API to be loaded if the
extension referencing the property also has all the permissions listed
in the ``permissions`` property.

A WebExtensions API that is controlled by a manifest key can also be loaded
when an extension that includes the relevant manifest key is activated.
This is specified by the ``manifest`` property, which lists any manifest keys
that should cause the API to be loaded.

Finally, APIs can be loaded based on other events in the WebExtension
lifecycle.  These are listed in the ``events`` property and described in
more detail in :ref:`lifecycle`.

Adding Experimental APIs in Privileged Extensions
-------------------------------------------------

A new API may also be implemented within a privileged extension. An API
implemented this way is called a WebExtensions Experiment (or simply an
Experimental API).  Experiments can be useful when actively developing a
new API, as they do not require building Firefox locally. These extensions
may be installed temporarily via ``about:debugging`` or, on browser that
support it (current Nightly and Developer Edition), by setting the preference
``xpinstall.signatures.required`` to ``false``.  You may also set the
preference ``extensions.experiments.enabled`` to ``true`` to install the
addon normally and test across restart.

.. note::
   Out-of-tree privileged extensions cannot be signed by addons.mozilla.org.
   A different pipeline is used to sign them with a privileged certificate.
   You'll find more information in the `xpi-manifest repository on GitHub <https://github.com/mozilla-extensions/xpi-manifest>`_.

Experimental APIs have a few limitations compared with built-in APIs:

- Experimental APIs can (currently) only be exposed to extension pages,
  not to devtools pages or to content scripts.
- Experimental APIs cannot handle manifest keys (since the extension manifest
  needs to be parsed and validated before experimental APIs are loaded).
- Experimental APIs cannot use the static ``"update"`` and ``"uninstall"``
  lifecycle events (since in general those may occur when an affected
  extension is not active or installed).

Experimental APIs are declared in the ``experiment_apis`` property in a
WebExtension's ``manifest.json`` file.  For example:

.. code-block:: js

  {
    "manifest_version": 2,
    "name": "Extension containing an experimental API",
    "experiment_apis": {
      "apiname": {
        "schema": "schema.json",
        "parent": {
          "scopes": ["addon_parent"],
          "paths": [["myapi"]],
          "script": "implementation.js"
        },

        "child": {
          "scopes": ["addon_child"],
          "paths": [["myapi"]],
          "script": "child-implementation.js"
        }
      }
    }
  }

This is essentially the same information required for built-in APIs,
just organized differently.  The ``schema`` property is a relative path
to a file inside the extension containing the API schema.  The actual
implementation details for the parent process and for child processes
are defined in the ``parent`` and ``child`` properties of the API
definition respectively.  Inside these sections, the ``scope`` and ``paths``
properties have the same meaning as those properties in the definition
of a built-in API (though see the note above about limitations; the
only currently valid values for ``scope`` are ``"addon_parent"`` and
``"addon_child"``).  The ``script`` property is a relative path to a file
inside the extension containing the implementation of the API.

The extension that includes an experiment defined in this way automatically
gets access to the experimental API.  An extension may also use an
experimental API implemented in a different extension by including the
string ``experiments.name`` in the ``permissions``` property in its
``manifest.json`` file.  In this case, the string name must be replace by
the name of the API from the extension that defined it (e.g., ``apiname``
in the example above.

Globals available in the API scripts global
-------------------------------------------

The API scripts aren't loaded as an JSM and so:

- they are not fully isolated from each other (and they are going to be
  lazy loaded when the extension does use them for the first time) and
  be executed in a per-process shared global scope)
- the experimental APIs embedded in privileged extensions are executed
  in a per-extension global (separate from the one used for the built-in APIs)

The global scope where the API scripts are executed is pre-populated with
some useful globals:

- ``AppConstants``
- ``console``
- ``CC``, ``Ci``, ``Cr`` and ``Cu``
- ``ChromeWorker``
- ``extensions``, ``ExtensionAPI``, ``ExtensionCommon`` and ``ExtensionUtils``
- ``global``
- ``MatchGlob``, ``MatchPattern`` and ``MatchPatternSet``
- ``Services``
- ``StructuredCloneHolder``
- ``XPCOMUtils``

For a more complete and updated list of the globals available by default in
all API scripts look to the following source:

- `SchemaAPIManager _createExtGlobal method <https://searchfox.org/mozilla-central/search?q=symbol:SchemaAPIManager%23_createExtGlobal&redirect=false>`_
- Only available in the parent Firefox process:
  `toolkit/components/extensions/parent/ext-toolkit.js <https://searchfox.org/mozilla-central/source/toolkit/components/extensions/parent/ext-toolkit.js>`_
- Only available in the child Firefox process:
  `toolkit/components/extensions/child/ext-toolkit.js <https://searchfox.org/mozilla-central/source/toolkit/components/extensions/child/ext-toolkit.js>`_
- Only available in the Desktop builds:
  `browser/components/extensions/parent/ext-browser.js <https://searchfox.org/mozilla-central/source/browser/components/extensions/parent/ext-browser.js>`_
- Only available in the Android builds:
  `mobile/android/components/extensions/ext-android.js <https://searchfox.org/mozilla-central/source/mobile/android/components/extensions/ext-android.js>`_

.. warning::
   The extension API authors should never redefine these globals to avoid introducing potential
   conflicts between API scripts (e.g. see `Bug 1697404 comment 3 <https://bugzilla.mozilla.org/show_bug.cgi?id=1697404#c3>`_
   and `Bug 1697404 comment 4 <https://bugzilla.mozilla.org/show_bug.cgi?id=1697404#c4>`_).

WebIDL Bindings
---------------

In ``manifest_version: 3`` the extension will be able to declare a background service worker
instead of a background page, and the existing WebExtensions API bindings can't be injected into this
new extension global, because it lives off the main thread.

To expose WebExtensions API bindings to the WebExtensions ``background.service_worker`` global
we are in the process of generating new WebIDL bindings for the WebExtensions API.

An high level view of the architecture and a more in depth details about the architecture process
to create or modify WebIDL bindings for the WebExtensions API can be found here:

.. toctree::
   :maxdepth: 2

   webidl_bindings