======= Shelves ======= .. note:: These APIs are not frozen and can change at any time without warning. See :ref:`the API versions available` for alternatives if you need stability. --------------------- Combined Hero Shelves --------------------- .. _hero-shelves: This convenience endpoint serves a single, randomly selected, primary hero shelf, and a single, randomly selected secondary hero shelf. .. http:get:: /api/v5/hero/ :query string lang: Activate translations in the specific language for that query. (See :ref:`translated fields `) :>json object primary: A :ref:`primary hero shelf `. :>json object secondary: A :ref:`secondary hero shelf `. -------------------- Primary Hero Shelves -------------------- .. _primary-hero-shelf: This endpoint returns all enabled primary hero shelves. As there will only ever be a small number of shelves this endpoint is not paginated. .. http:get:: /api/v5/hero/primary/ :query string lang: Activate translations in the specific language for that query. (See :ref:`translated fields `) :query boolean all: return all shelves - both enabled and disabled. To be used internally to generate .po files containing the strings defined by the content team. :query string raw: 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. :>json array results: The array containing the results for this query. :>json object results[].gradient: The background colors used for the gradient. :>json string results[].gradient.start: The starting color name for gradient - typically top or left. The name is from the `photon color variables `_. :>json string results[].gradient.end: The ending color name for gradient - typically bottom or right. The name is from the `photon color variables `_. :>json string|null results[].featured_image: The image used to illustrate the item, if set. :>json object|null results[].description: The description for this item, if any. (See :ref:`translated fields `. Note: when ``lang`` is not specified, not all locales will be returned, unlike other translated fields). :>json object results[].addon: The :ref:`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 ``file`` fields present), ``guid``, ``icon_url``, ``name``, ``ratings``, ``previews``, ``promoted``, ``slug``, ``theme_data``, ``type``, and ``url``. :>json object results[].external: The :ref:`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 ---------------------- .. _secondary-hero-shelf: 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. .. http:get:: /api/v5/hero/secondary/ :query string lang: Activate translations in the specific language for that query. (See :ref:`translated fields `) :query boolean all: return all shelves - both enabled and disabled. To be used internally to generate .po files containing the strings defined by the content team. :>json array results: The array containing the results for this query. :>json object|null results[].headline: The headline for this item. (See :ref:`translated fields `. Note: when ``lang`` is not specified, not all locales will be returned, unlike other translated fields). :>json object|null results[].description: The description for this item. (See :ref:`translated fields `. Note: when ``lang`` is not specified, not all locales will be returned, unlike other translated fields). :>json object|null results[].cta: The optional call to action link and text to be displayed with the item. :>json string results[].cta.url: The url the call to action would link to. :>json string results[].cta.outgoing: (v5+ only) url wrapped with outgoing (See :ref:`Outgoing Links `) :>json object|null results[].cta.text: The call to action text. (See :ref:`translated fields `. Note: when ``lang`` is not specified, not all locales will be returned, unlike other translated fields). :>json array results[].modules: The modules for this shelf. Should always be 3. :>json string results[].modules[].icon: The icon used to illustrate the item. :>json object|null results[].modules[].description: The description for this item. (See :ref:`translated fields `. Note: when ``lang`` is not specified, not all locales will be returned, unlike other translated fields). :>json object|null results[].modules[].cta: The optional call to action link and text to be displayed with the item. :>json string results[].modules[].cta.url: The url the call to action would link to. :>json string results[].modules[].cta.outgoing: (v5+ only) url wrapped with outgoing (See :ref:`Outgoing Links `) :>json object|null results[].modules[].cta.text: The call to action text. (See :ref:`translated fields `. Note: when ``lang`` is not specified, not all locales will be returned, unlike other translated fields). ---------------- Homepage Shelves ---------------- .. _homepage-shelves: This endpoint returns the shelves to display on the AMO Homepage. A single, randomly selected, primary hero shelf and a single, randomly selected secondary hero shelf is returned, along with the enabled shelves. As there will only ever be a small number of shelves this endpoint is not paginated. .. http:get:: /api/v5/shelves/ :query string lang: Activate translations in the specific language for that query. (See :ref:`translated fields `) :>json array results: The array of shelves displayed on the AMO Homepage. :>json object|null results[].title: The title of the shelf. (See :ref:`translated fields `. Note: when ``lang`` is not specified, not all locales will be returned, unlike other translated fields). :>json string results[].url: The configured URL using the shelf's endpoint and criteria; links to the shelf's returned add-ons. :>json string results[].endpoint: The :ref:`endpoint type ` selected for the shelf. :>json string results[].addon_type: The :ref:`add-on type ` selected for the shelf. :>json object results[].footer: The footer to be displayed with the shelf. :>json string results[].footer.url: The url for the footer text. :>json string results[].footer.outgoing: url wrapped with outgoing (See :ref:`Outgoing Links `) :>json object|null results[].footer.text: The optional text in the footer of the shelf. (See :ref:`translated fields `. Note: when ``lang`` is not specified, not all locales will be returned, unlike other translated fields). :>json array results[].addons: An array of :ref:`add-ons `. :>json object|null primary: A :ref:`primary hero shelf `. :>json object|null secondary: A :ref:`secondary hero shelf `. .. _shelf-endpoint-type: Possible values for the ``endpoint`` field: ============== ============================================================= Value Description ============== ============================================================= search an :ref:`addon search`. collections a mozilla :ref:`collection`. random-tag a search for addons matching a randomly chosen tag each time. ============== ============================================================= ---------------------------------- Homepage Shelves Editorial Content ---------------------------------- .. _homepage-shelves-editorial: This endpoint allows you to fetch all editorial content for Homepage Shelves. This is used internally to generate .po files containing the strings defined by the content team. .. http:get:: /api/v5/shelves/editorial :>json array results: The array of shelves displayed on the AMO Homepage. :>json string|null results[].title: The title of the shelf. :>json string|null results[].footer_text: The optional text in the footer of the shelf.