======= Shelves ======= .. note:: These v4 APIs are now frozen. See :ref:`the API versions available` for details of the different API versions available. --------------------- Combined Hero Shelves --------------------- .. _v4-hero-shelves: This convenience endpoint serves a single, randomly selected, primary hero shelf, and a single, randomly selected secondary hero shelf. .. http:get:: /api/v4/hero/ :query string lang: Activate translations in the specific language for that query. (See :ref:`translated fields `) :query string wrap_outgoing_links: (v3/v4 only) If this parameter is present, wrap outgoing links through ``outgoing.prod.mozaws.net`` (See :ref:`Outgoing Links `) :>json object primary: A :ref:`primary hero shelf `. :>json object secondary: A :ref:`secondary hero shelf `. -------------------- Primary Hero Shelves -------------------- .. _v4-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/v4/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. :query string wrap_outgoing_links: (v3/v4 only) If this parameter is present, wrap outgoing links through ``outgoing.prod.mozaws.net`` (See :ref:`Outgoing Links `) :>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 string|null results[].description: The description for this item, if any. :>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 ``files`` 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 ---------------------- .. _v4-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/v4/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. :query string wrap_outgoing_links: (v3/v4 only) If this parameter is present, wrap outgoing links through ``outgoing.prod.mozaws.net`` (See :ref:`Outgoing Links `) :>json array results: The array containing the results for this query. :>json string results[].headline: The headline for this item. :>json string results[].description: The description for this item. :>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 string results[].cta.text: The call to action text. :>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 string results[].modules[].description: The description for this item. :>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 string results[].modules[].cta.text: The call to action text.