Overview

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/v3/...
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."]
}

Translated fields

Fields that can be translated by users (typically name, description) have a special behaviour. The default is to return them as an object, with languages as keys and translations as values:

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