A new API for submitting and updating add-ons

The addons.mozilla.org (AMO) external API has offered add-on developers the ability to submit new add-on versions for signing for a number of years, in addition to being available to get data about published add-ons directly or internally inside Firefox.

Current “signing” API

Currently, the signing api offers some functionality, but it’s limited – you can’t submit the first listed version of an add-on (extra metadata is needed to be collected via developer hub); you can’t edit existing submissions; you can’t submit/edit extra metadata about the add-on/version; and you can’t share the source code for an add-on when it’s needed to comply with our policies. For all of those tasks you need to use the forms on the appropriate developer hub web pages.

New Add-on “submission” API

The new add-on submission api aims to overcome these limitations and (eventually) allow developers to submit and manage all parts of their add-on via the API. It’s available now in our v5 api, and should be seen as beta quality for now.

Submission Workflow

The submission workflow is split by the process of uploading the file for validation, and attaching the validated file to a new add-on, or as a new version to an existing add-on.

1. The add-on file to be distributed is uploaded via the upload create endpoint, along with the channel, returning an upload uuid.
2. The upload detail endpoint can be polled for validation status.
3. Once the response has "valid": true, it can be used to create either a new add-on, or a new version of an existing add-on. Sources may be attached if required.

Uploading the add-on file

Regardless of if you are creating a new add-on or adding a new version to an existing add-on, you will need to upload the file for validation first. Here you will decide if the file will be associated with a public listing (listed), or will be self-hosted (unlisted). See our guide on signing and distribution for further details.

# Send a POST request to the upload create endpoint
# Pass addon.xpi as a file using multipart/form-data, along with the
# distribution channel.
curl -XPOST "https://addons.mozilla.org/api/v5/addons/upload/" \
  -H "Authorization: <JWT blob>" \
  -F "upload=@addon.xpi" -F "channel=listed" 

The response will provide information on successful validation, if valid is set to true you will be able to use the uuid in the next submission steps. The recommended polling interval is 5-10 seconds, making sure your code times out after a maximum of 10 minutes.

Creating a new add-on

When creating a new add-on, we require some initial metadata to describe what the add-on does, as well as some optional fields that will allow you to create an appealing listing. Make a request to the add-ons create endpoint to attach the uploaded file to a new add-on:

# Send a POST request to the add-ons create endpoint
# Include the add-on metadata as JSON.
curl -XPOST "https://addons.mozilla.org/api/v5/addons/addon/" \
  -H "Authorization: <JWT blob>" \
  -H "Content-Type: application/json" -d @- <<EOF
{
  "categories": {
    "firefox": ["bookmarks"]
  },
  "summary": {
    "en-US": “This add-on does great things!”
  },
  "version": {
    "upload": "<upload-uuid>",
    "license": "MPL-2.0"
  }
}
EOF

When submitting to the self-hosted channel, you can omit extra metadata such as categories, summary or license.

Adding a version to an existing add-on

If instead you are  adding a version to an existing add-on, the metadata has already been provided in the initial submission. The following request can be made to attach the version to the add-on:

# Send a POST request to the versions create endpoint.
# Include the upload uuid from the previous add-on upload
curl -XPOST "https://addons.mozilla.org/api/v5/addons/addon/<add-on id>/versions/" \
  -H "Authorization: <JWT blob>" -H "Content-Type: application/json" \
  -d '{ "upload": <upload-uuid> }'

Updating existing add-on or version metadata

Metadata on any existing add-ons or versions can be updated, regardless of how they have been initially submitted. To do so, you can use the add-on edit or version edit endpoints. For example:

# Send a PATCH request to the add-ons edit endpoint
# Set the slug and tags as JSON data.
curl -XPATCH "https://addons.mozilla.org/api/v5/addons/addon/<add-on id>/" \ \
  -H "Authorization: <JWT blob>" -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "slug": "new-slug",
  "tags": ["chat", "music"]
}
EOF

Providing Source code

When an add-on/version submission requires source code to be submitted it can either be uploaded while creating the version, or as an update to an existing version.  Files are always uploaded as multipart/form-data rather than JSON so setting source can’t be combined with every other field.

# Send a PATCH request to the version edit endpoint
# Pass source.zip as a file using multipart/form-data, along with the license field.
curl -XPATCH "https://addons.mozilla.org/api/v5/addons/addon/<add-on id>/versions/<version-id>/"  \
  -H "Authorization: <JWT blob>" \
  -F "source=@source.zip" -F "license=MPL-2.0"

You may also provide the source code as part of adding a version to an existing add-on. Fields such as compatibility, release_notes or custom_license can’t be set at the same time because complex data structures (lists and objects) can only be sent as JSON.

# Send a POST request to the version create endpoint
# Pass source.zip as a file using multipart/form-data,
# along with the upload field set to the uuid from the previous add-on upload.
curl -XPOST "https://addons.mozilla.org/api/v5/addons/addon/<add-on id>/versions/" \
  -H "Authorization: <JWT blob>" \
  -F "source=@source.zip" -F "upload=500867eb-0fe9-47cc-8b4b-4645377136b3"

Future work and known limitations

There may be bugs – if you find any please file an issue! – and the work is still in progress, so there are some known limitations where not all add-on/version metadata that is editable via developer hub can be changed yet, such as adding/removing add-on developers, or uploading icons and screenshots.

Right now the web-ext tool (or sign-addon) doesn’t use the new submission API (they use the signing api); updating those tools is next on the roadmap.

Longer term we aim to replace the existing developer hub and create a new webapp that will use the add-on submission apis directly, and also deprecate the existing signing api, leaving a single method of uploading and managing all add-ons on addons.mozilla.org.