Overview — addons-server documentation (original) (raw)

Note

These APIs are not frozen and can change at any time without warning. See the API versions available for details if you need stability.

This describes the details of the requests and responses you can expect from the addons.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 a HTTP 400 Bad Request response, the API will try to return some information about the error(s) in the body of the response, as a JSON object. The keys of that object indicate the field(s) that caused an error, and for each, a list of messages will be provided (often only one message will be present, but sometimes more). If the error is not attached to a specific field the key non_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 returning HTTP 401 Unauthorized and HTTP 403 Permission Deniedresponses, the API will try to return some information about the error in the body of the response, as a JSON object. A detail property will contain a message explaining the error. In addition, in some cases, an optional codeproperty will be present and will contain a constant corresponding to specific problems to help clients address the situation programmatically. The constants are as follows:

Value Description
ERROR_INVALID_HEADER The Authorization 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 probably invalid.
ERROR_AUTHENTICATION_EXPIRED The payload references an invalid session hash, probably because the session has expired.

Maintenance Mode

When returning HTTP 503 Service Unavailable responses the API may be in read-only mode. This means that for a short period of time we do not allow any write requests, this includes POST, PATCH, PUT and DELETE requests.

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

The response when returning HTTP 503 Service Unavailable 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, the site status api can be called.

Translated Fields

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

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

However, for performance, if you pass the lang parameter to a GETrequest, then only the most relevant translation (the specified language or the fallback, depending on whether a translation is available in the requested language) 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 a lang parameter for a language that doesn’t exist for that object then a fallback translation is returned, the requested language is included with a value of null, 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 _).

For POST, PATCH and PUT requests you submit an object containing translations for any languages needing to be updated/saved. Any language not in 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, pass null as the value for that language.

Outgoing Links

All fields that can have external links that would be presented to the user, such as support_url or homepage, are returned as a object both containing the original url (url), and wrapped through outgoing.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 the url and outgoingvalues could be an object rather than a string (See translated fields for translated field representations).

Fields supporting some Markdown, such as add-on description or license, always wrap any links directly inside the content (the original url is not available).

Cross Origin

All APIs are available with Cross-Origin Resource Sharing unless otherwise specified.

Site Status

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

GET /api/v5/site/

Response JSON Object:

API Versions

Default v5 API

All documentation here, unless otherwise specified, refers to the default v5 APIs, which are considered stable. The request and responses are NOT 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 using the v4 API instead, which is frozen. No new API endpoints (so no new features) will be added to v4 and we aim to make no breaking changes. Despite the aim, we can’t guarantee 100% stability.

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

Deprecated v3 API

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

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

v4 API changelog

v5 API changelog

These are v5 specific changes - v4 changes apply also.