Shelves

Note

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

Combined Hero Shelves

This convenience endpoint serves a single, randomly selected, primary hero shelf, and a single, randomly selected secondary hero shelf.

GET /api/v4/hero/
Query Parameters:

  • lang (string) – Activate translations in the specific language for that query. (See translated fields)

  • wrap_outgoing_links (string) – (v3/v4 only) If this parameter is present, wrap outgoing links through outgoing.prod.mozaws.net (See Outgoing Links)

Response JSON Object:

Primary Hero Shelves

This endpoint returns all enabled primary hero shelves. As there will only ever be a small number of shelves this endpoint is not paginated.

GET /api/v4/hero/primary/
Query Parameters:

  • lang (string) – Activate translations in the specific language for that query. (See translated fields)

  • all (boolean) – return all shelves - both enabled and disabled. To be used internally to generate .po files containing the strings defined by the content team.

  • raw (string) – If this parameter is present, don’t localise description or fall-back to addon metadata. To be used internally to generate .po files containing the strings defined by the content team.

  • wrap_outgoing_links (string) – (v3/v4 only) If this parameter is present, wrap outgoing links through outgoing.prod.mozaws.net (See Outgoing Links)

Response JSON Object:

  • results (array) – The array containing the results for this query.

  • results[].gradient (object) – The background colors used for the gradient.

  • results[].gradient.start (string) – The starting color name for gradient - typically top or left. The name is from the photon color variables.

  • results[].gradient.end (string) –

    The ending color name for gradient - typically bottom or right. The name is from the photon color variables.

  • results[].featured_image (string|null) – The image used to illustrate the item, if set.

  • results[].description (string|null) – The description for this item, if any.

  • results[].addon (object) – The add-on for this item if the addon is hosted on AMO. Either this field or external will be present. Only a subset of fields are present: id, authors, average_daily_users, current_version (with only the id, compatibility, is_strict_compatibility_enabled and files fields present), guid, icon_url, name, ratings, previews, promoted, slug, theme_data, type, and url.

  • results[].external (object) – The add-on for this item if the addon is externally hosted. Either this field or addon will be present. Only a subset of fields are present: id, guid, homepage, name and type.

Secondary Hero Shelves

This endpoint returns all enabled secondary hero shelves. As there will only ever be a small number of shelves - and likely only one - this endpoint is not paginated.

GET /api/v4/hero/secondary/
Query Parameters:

  • lang (string) – Activate translations in the specific language for that query. (See translated fields)

  • all (boolean) – return all shelves - both enabled and disabled. To be used internally to generate .po files containing the strings defined by the content team.

  • wrap_outgoing_links (string) – (v3/v4 only) If this parameter is present, wrap outgoing links through outgoing.prod.mozaws.net (See Outgoing Links)

Response JSON Object:

  • results (array) – The array containing the results for this query.

  • results[].headline (string) – The headline for this item.

  • results[].description (string) – The description for this item.

  • results[].cta (object|null) – The optional call to action link and text to be displayed with the item.

  • results[].cta.url (string) – The url the call to action would link to.

  • results[].cta.outgoing (string) – (v5+ only) url wrapped with outgoing (See Outgoing Links)

  • results[].cta.text (string) – The call to action text.

  • results[].modules (array) – The modules for this shelf. Should always be 3.

  • results[].modules[].icon (string) – The icon used to illustrate the item.

  • results[].modules[].description (string) – The description for this item.

  • results[].modules[].cta (object|null) – The optional call to action link and text to be displayed with the item.

  • results[].modules[].cta.url (string) – The url the call to action would link to.

  • results[].modules[].cta.outgoing (string) – (v5+ only) url wrapped with outgoing (See Outgoing Links)

  • results[].modules[].cta.text (string) – The call to action text.