Overview

Note

These v4 APIs are now frozen. See the API versions available for details of the different API versions available.

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/v4/...
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 Denied responses, 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 code property 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.

Maintainance 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:

  • GET requests behave normally

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

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 GET request, 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.

Default API behavior

In API version 3 or 4 the response, if the lang parameter is passed, is a single string.

{
    "name": "Games"
}

This behaviour also applies to POST, PATCH and PUT requests: you can either submit an object containing several translations, or just a string. If only a string is supplied, it will only be used to translate the field in the current language.

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 maintainance mode for more details of when the site is read only and how requests are affected.

GET /api/v4/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.

v4 API changelog