THIS PAGE IS A WORKING DRAFT
	The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page.

AMO API

Purpose

Making our add-on data available in XML or JSON form will allow extension developers and web developers to do creative things that enhance the web.

Defining and accepting a format for inputting data would also be interesting (eg. add-on localization).

An example use of this service would be a Thunderbird/Sunbird add-on browser/installer.

Requests/Responses

Requests

Requests will be made via GET or POST in a form similar to the following: https://addons.mozilla.org/%LANG%/%APP%/api/%ACTION%/%ACTION_SPECIFIC_PARAMS%/?key=%API_KEY%

Response Formats

The format of the response may be altered by using the format parameter. If the format parameter is absent, the data will be returned using JSON.

XML

<addons>
  <addon>
    <id>10</id>
    <name lang="en-US">Adblock</name>
    <totaldownloads>1203402</totaldownloads>
  </addon>
  <addon>
    <id>2848</id>
    <name>Password Exporter</name>
    <totaldownloads>90000</totaldownloads>
  </addon>
</addons>

JSON

{addons:
  {
    1:{
      id: 10,
      name: 'Adblock',
      totaldownloads: 1203402
    },

    2:{
      id: 2848,
      name: 'Password Exporter',
      totaldownloads: 90000
    }
  }
}

Serialized PHP

a:2:{
  s:6:"addons";
  a:3:{
    s:2:"id";
      i:10;
    s:4:"name";
      s:7:"Adblock";
    s:14:"totaldownloads";
      i:1203402;
  }
  i:0;
  a:3:{
    s:2:"id";
      i:2848;
    s:4:"name";
      s:17:"Password Exporter";
    s:14:"totaldownloads";
      i:90000;
  }
}

To Cake or not to Cake

We don't use Cake for updates, blocklist, and other similar services; however, those services do not require the extensive localization that an API will.

If we utilize Cake, we can keep the /%LOCALE%/%APP% format used throughout the rest of the site, as well as have action processing already setup. We also have localization setup in Cake such that it is painless to switch locales and fall back.

If we don't utilize Cake, we would probably have some performance increase.

Actions

This is a very preliminary list of actions that would be useful for a first implementation:

• getAddonsByAddontype
  • Retrieve list of all add-ons by type
  • Parameters: addontype_id, fields, limit
• getAddonsByCategory
  • Retrieve list of all add-ons in a category
  • Parameters: category_id, fields, limit
• getAddon
  • Retrieve information on a specific add-on by id, along with most recent version and files
  • Parameters: addon_id, fields

Maybe not for a first implementation, but something to think about:

• Submitting localization for an add-on. This would allow external sites like babelzilla, etc. to submit localizations for add-ons from their site.

Available Data

The API needs to ensure that the same permission and accessibility checks done in the web interface are also done here. This involves:

• not returning sandboxed add-ons
• not returning disabled add-ons
• only returning STATUS_PUBLIC add-ons and files
• not returning add-ons with a EULA (or returning without a file download url and an indication as to why)

We should also have a whitelist of fields that we will return that the requested field list is checked against.

Fields that should not be returned for security reasons:

• Can't think of any at the moment, at least in addons/versions/files tables

Fields that should not be returned for other reasons:

• Instead of icondata/icontype, we should return a url to the icon
• Same with previews

API Keys

I think that we should require users to obtain an API key from us that is associated with their user account and passed on every request. That key should be able to be denied access in case of abuse or other Bad Things.

• Keys will prevent caching the URLs won't they?
  • Unfortunately they'll prevent caching globally, but the cache will still be there for anyone hitting the API too hard (which will mask their abuse, negating the need for keys in the first place ;)). I guess it's really a question of how aggressively we're willing to cache and whether we think we could just get away with recording calling IPs and tracking usage that way.