Overview

Note

These APIs are not frozen and can change at any time without warning.Seethe API versions available for detailsif you need stability.

This describes the details of the requests and responses you can expect fromtheaddons.mozilla.org API.

Requests

All requests should be made with the header:

Content-type:application/json

Responses

Status Codes

There are some common API responses that you can expect to receive at times.

GET/api/v5/...
Status Codes:

Bad Requests

When returning aHTTP400BadRequest response, the API will try to returnsome information about the error(s) in the body of the response, as a JSONobject. The keys of that object indicate the field(s) that caused an error, andfor each, a list of messages will be provided (often only one message will bepresent, but sometimes more). If the error is not attached to a specific fieldthe keynon_field_errors will be used instead.

Example:

{"username":["This field is required."],"non_field_errors":["Error not linked to a specific field."]}

Unauthorized and Permission Denied

When returningHTTP401Unauthorized andHTTP403PermissionDeniedresponses, the API will try to return some information about the error in thebody of the response, as a JSON object. Adetail property will contain amessage explaining the error. In addition, in some cases, an optionalcodeproperty will be present and will contain a constant corresponding tospecific problems to help clients address the situation programmatically. Theconstants are as follows:

Value

Description

ERROR_INVALID_HEADER

TheAuthorization header is invalid.

ERROR_SIGNATURE_EXPIRED

The signature of the token indicates it has expired.

ERROR_DECODING_SIGNATURE

The token was impossible to decode and probablyinvalid.

ERROR_AUTHENTICATION_EXPIRED

The payload references an invalid session hash,probably because the session has expired.

Maintenance Mode

When returningHTTP503ServiceUnavailable responses the API may be inread-only mode. This means that for a short period of time we do not allow anywrite requests, this includesPOST,PATCH,PUT andDELETE requests.

In case we are in read-only mode, the following behavior can be observed:

  • GET requests behave normally

  • POST,PUT,PATCH, andDELETE requests return 503 with a json response that contains a localized error message

The response when returningHTTP503ServiceUnavailable in case of read-only mode looks like this:

{"error":"Some features are temporarily disabled while we perform websi…"}

In case we are not in read-only mode everything should be back working as normal.To check if the site is in read-only mode before submitting a response, thesite status api can be called.

Pagination

By default, all endpoints returning a list of results are paginated.The default number of items per page is 25 and clients can use thepage_sizequery parameter to change it to any value between 1 and 50. Exceptions to thoserules are possible but will be noted in the corresponding documentation foraffected endpoints.

The following properties will be available in paginated responses:

  • next: the URL for the next page in the pagination.

  • previous: the URL for the previous page in the pagination.

  • page_size: The number of items per page in the pagination.

  • page_count: The number of pages available in the pagination. It may belower thancount / page_size for elasticsearch based paginations thatgo beyond ourmax_result_window configuration.

  • count: the total number of records.

  • results: the array containing the results for this page.

Translated Fields

Fields that can be translated by users (typically name, description) have aspecial behaviour. They are returned as an object, by default, with languages as keys andtranslations as values, and by default all languages are returned:

{"name":{"en-US":"Games","fr":"Jeux","kn":"ಆಟಗಳು"}}

However, for performance, if you pass thelang parameter to aGETrequest, then only the most relevant translation (the specified language or thefallback, depending on whether a translation is available in the requestedlanguage) will be returned, and the other translations are omitted from the response.The response is always an object.

For example, for a request?lang=en-US:

{"name":{"en-US":"Games"}}

If, however, a request is made with alang parameter for a language that doesn’t exist for that objectthen a fallback translation is returned, the requested language is included with a value ofnull, and the language of the fallback is indicated.For example, for a request?lang=de:

{"name":{"en-US":"Games","de":null,"_default":"en-US"}}

Warning

lang must only contains alphanumeric characters (plus- and_).

ForPOST,PATCH andPUT requests you submit an object containingtranslations for any languages needing to be updated/saved. Any language notin the object is not updated, but is not removed.

For example, if there were existing translations of:

"name":{"en-US":"Games","fr":"Jeux","kn":"ಆಟಗಳು"}

and the following data was submitted in a request:

{"name":{"en-US":"Fun"}}

Then the resulting translations would be:

"name":{"en-US":"Fun","fr":"Jeux","kn":"ಆಟಗಳು"}

To delete a translation, passnull as the value for that language.

Outgoing Links

All fields that can have external links that would be presented to the user,such assupport_url orhomepage, are returned as a object both containing theoriginal url (url), and wrapped throughoutgoing.prod.mozaws.net (outgoing).

{"contributions":{"url":"https://paypal.me/xxx","outgoing":"https://outgoing.prod.mozaws.net/123456"}}

Note, if the field is also a translated field then theurl andoutgoingvalues could be an object rather than a string(Seetranslated fields for translated field representations).

Fields supporting some Markdown, such as add-ondescription orlicense,always wrap any links directly inside the content (the original url is notavailable).

Cross Origin

All APIs are available withCross-Origin Resource Sharing unless otherwisespecified.

Site Status

This special endpoint returns if the site is in read only mode, and if there is a site notice currently in effect.Seemaintenance mode for more details of when the site is read only and how requests are affected.

GET/api/v5/site/
Response JSON Object:

  • read_only (boolean) – Whether the site in read-only mode.

  • notice (string|null) – A site-wide notice about any current known difficulties or restrictions. If this API is being consumed by a tool/frontend it should be displayed to the user.

API Versions

Default v5 API

All documentation here, unless otherwise specified, refers to the defaultv5 APIs,which are considered stable.The request and responses areNOT frozen though, and can change at any time,depending on the requirements of addons-frontend (the primary consumer).

Frozen v4 API

Any consumer of the APIs that requires more stablity may consider usingthev4 API instead, which is frozen. No new API endpoints (so no new features)will be added tov4 and we aim to make no breaking changes.Despite the aim, we can’t guarantee 100% stability.

The documentation forv4 can be accessed at:External API (V4 - Frozen)

Deprecated v3 API

Thev3 is now deprecated. If you are using this API you should switch tov4,which is now frozen.Thev3 API will be maintained and available until at least 31st December 2021.

The documentation forv3 can be accessed at:External API (V3 - Deprecated)

v4 API changelog

v5 API changelog

These arev5 specific changes -v4 changes apply also.