Overview

Note

These APIs are experimental and are currently being worked on. Endpoints may change without warning. Consider the v3 API 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/v4/...
Status Codes:
  • 200 OK – Success.
  • 201 Created – Creation successful.
  • 202 Accepted – The request has been accepted for processing. This usually means one or more asyncronous tasks is being executed in the background so results aren’t immediately visible.
  • 204 No Content – Success (no content is returned).
  • 400 Bad Request – There was a problem with the parameters sent with this request.
  • 401 Unauthorized – Authentication is required or failed.
  • 403 Forbidden – You are not permitted to perform this action.
  • 404 Not Found – The requested resource could not be found.
  • 500 Internal Server Error – An unknown error occurred.
  • 503 Service Unavailable – The site is in maintenance mode at this current time and the operation can not be performed.

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 and DELETE requests.

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

  • GET requests behave normally
  • POST, PUT and DELETE requests return 503 with a json response that contains a localized error message
  • A custom X-AMO-Read-Only header is set to true
  • A Retry-After header may be set, it’s not a requirement though and can be omitted

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

  • GET, POST, PUT, DELETE requests behave normally again
  • X-AMO-Read-Only header is set to false

So, in case of a 503 HTTP response you can always check the X-AMO-Read-Only header to behave appropriately.

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 4 the response if the lang parameter is passed a single string is returned.

{
    "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.

Alternate API (v4dev) behavior

On the addons-dev.allizom.org (dev) and addons.allizom.org servers (stage) servers an additional API version, v4dev is available. v4dev is not available on production AMO (addons.mozilla.org). In 4dev the response if the lang parameter is passed is an object only containing that translation is returned.

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

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 request was made:

{
    "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. (Note: this behavior is currently buggy/broken - see https://github.com/mozilla/addons-server/issues/8816 for more details)

Cross Origin

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

Stable v3 API

All documentation here refers to the in-development v4 APIs, which are experimental. Any consumer of the APIs that require stablity may consider using the v3 API instead, which is frozen. No new API endpoints will be added to v3 and we aim to make no breaking changes. (That’s the aim - we can’t guarantee 100% stability). The v3 API will be maintained for as long as Firefox ESR60 is supported by Mozilla, i.e. at least June 30th 2019. The downside of using the v3 API is, of course, no new cool features!

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

v4 API changelog