Overview¶

This describes the details of the requests and responses you can expect from the Firefox Marketplace API.

Requests¶

All requests should be made with the header:

Content-type: application/json

If you access the URLs in this document in a browser, then prepend ?format=json on to the request.

Verbs¶

This follows the order of the django-tastypie REST verbs.

GET gets an individual resource or listing.
POST creates a resource.
PUT replaces a resource, so this alters all the data on an existing resource.
PATCH alters some parts of an existing resource.
DELETE deletes an object.

A GET that accesses a standard listing object, also accepts the parameters in the query string for filtering the result set down.

A POST, PUT and PATCH accept parameters as either:

a JSON document in the body of the request, if so the Content-Type must be set to applicationjson or
form urlencoded values in the body of the request, if so the Content-Type must be set to application/x-www-form-urlencoded

If you are unable to make the correct kind of request, you send a request using any verb with the header X-HTTP-METHOD-OVERRIDE containing the verb you would like to use.

Versions¶

This API is versioned and the version is indicated in the URL, for example:

/api/v2/...

Version	Status	Notes
v1	Stable
v2	Development	For feed

Deprecated this API has been deprecated and will be removed at some point in the future. Clients using this API should upgrade to a stable version.
Development this API is subject to change and should not be relied upon until made stable.
Stable this API is stable and will not change unless there is a security or privacy issue.

The current policy for how long deprecated APIs will exist has not been defined, but it would include time for any clients to upgrade before versions are turned off.

If you are using a deprecated version of the API then you will get a HTTP header in the response:

API-Status: Deprecated

We will also return the version of the API we think you are using in HTTP header:

API-Version: 1

Modifying Results¶

In order to return the most relevant results for the client, the API attempts to detect and filter responses by region and language. Additionally, it is possible to globally restrict responses by device type and carrier.

The API will report which filters are implemented via the URL-encoded API-Filter header in responses:

API-Filter: lang=en-US&device=&region=us&carrier=

In some cases, such as that where the API consumer is actually a proxy for the end user, it may be appropriate to manually set one or more of these parameters.

Carrier¶

Responses may be modified to include results relevent to a specific carrier by passing the carrier querystring parameter. This must be set to a slug representing an item from the list of carriers.

Region¶

Responses may be modified to include results relevent to a specific region by passing the region querystring parameter. This must be set to a slug representing an item from the list of regions.

Language¶

Responses may be filtered to only include results for a specific language. This is done by inspecting the value of the Accept-Language header on the request. This value may be overriden via the lang querystring parameter. This may be set to any of the valid RFC 3060 languages.

Device¶

Responses may be filtered to only include results relevant for one or more types of devices.

gaia - return results relevant to Gaia.
mobile - return results relevant to mobile devices.
tablet - return results relevant to tablets.

The API-Filter header will represent this as a representation of a list in a queryset:

API-Filter: device=mobile&device=gaia

You may override these values with separate querystring values for each device type:

gaia=true&mobile=true&tablet=false

Responses¶

Because the responses can be quite long, rather than show the full result, we link to examples of the results. All responses are in JSON. The client must send either no HTTP Accept header, or a value of applicationjson. Any other value will result in 400 status code.

Data errors¶

If there is an error in your data, a 400 status code will be returned. There can be multiple errors per field. Example:

{
    "error_message": {
        "manifest": ["This field is required."]
    }
}

Rate limiting¶

Select API endpoints are rate-limited. When an application exceeds the rate limit for a given endpoint, the API will return an HTTP 429 response.

Other errors¶

The appropriate HTTP status code will be returned, with the error in JSON.

Listings¶

When the API returns a list of objects, it will generally return a response in the same manner every time. There are a few exceptions for specialised API’s and these are noted.

A listing API will return a two elements, meta and objects. Rather than include this output in all the API docs, we will link to these documents or the relevant object.

Listing response meta¶

This is information about the object listing so that the client can paginate through the listing with. For example:

{
    "meta": {
        "limit": 3,
        "next": "/api/v2/apps/category/?limit=3&offset=6",
        "offset": 3,
        "previous": "/api/v2/apps/category/?limit=3&offset=0",
        "total_count": 16
    }
}

The properties in that meta object are:

limit: the number of records requested. The maximum value allowed is 50.
offset: where in the result set the listing started.
next: the URL for the next page in the pagination.
previous: the URL for the previous page in the pagination.
total_count: the total number of records.

Listing query params¶

The following query params can be passed through to any listing page to access a different page.

limit: the number of records to return. The default is 25, and the maximum allowed value is 50.
offset: where in the result set the listing should start (so if your limit is 25, to get the second page of result, you’d need to use offset=25).

Listing response objects¶

This is a list of the objects returned by the listing. The contents of the objects depends upon the listing in question. For example:

{
    "objects": [{
        "name": "Music",
        "slug": "music"
    }, {
        "name": "News",
        "slug": "news"
    }, {
        "name": "Productivity",
        "slug": "productivity"
    }]
}

All objects in the database will have at least two fields:

id: the unique id of that object.
resource_uri: the URL of that object for more detailed information.

Translations¶

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 sake, 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) will be returned as a string.

"name": "Games"

This behaviour also applies to POST, PATCH and PUT requests: you can either submit a 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.

Timestamps¶

Timestamps use the %Y-%m-%dT%H:%M:%S format (Python’s strftime notation), using the America/Los_Angeles time zone.