New in version 2.

Feed¶

The feed is a stream of content relevant to the user displayed on the Marketplace home page. The feed is comprised of a number of feed items, each containing a singular of piece of content. Currently, the feed may include:

Note

GET, HEAD, and OPTIONS requests to these endpoints may be made anonymously. Authentication and the Feed:Curate permission are required to make any other request.

Note

New in version 2 of the API.

Feed¶

GET /api/v2/feed/get/?carrier=(str: carrier)&region=(str: region)¶

A convenience endpoint containing all the data necessary for a user’s feed, which currently includes:

All the feed items.

If an operator shelf is available for the passed in carrier + region, it appear first in the list of feed items in the respnse.

Request

Parameters:	carrier (str) – the slug of a carrier. Omit if no carrier is available. region (str) – the slug of a region. Omit if no region is available.

Response

Parameters:	meta (object) – Listing response meta. objects (array) – An ordered list of feed items for the user.

{
    "objects": [
        {
            "id": 343,
            ...
        },
        {
            "id": 518,
            ...
        }
    ],
}

Feed Items¶

A feed item wraps a feed app, feed brand, or feed collection with additional metadata regarding when and where to feature the content. Feed items are represented thusly:

{
    "app": null,
    "brand": null,
    "carrier": "telefonica",
    "collection": {
        "data": "..."
    }
    "id": 47,
    "item_type": "collection",
    "region": "br",
    "resource_url": "/api/v2/feed/items/47/",
    "shelf": null
}

app: object|null - the full representation of a feed app.
brand: object|null - the full representation of a feed brand.
carrier: string|null - the slug of a carrier. If defined, this feed item will only be available by users of that carrier.
category: string|null - the slug of a category. If defined, this feed item will only be available to users browsing that category.
collection: object|null - the full representation of a collection.
id: int the ID of this feed item.
item_type: string - the type of object being represented by this feed item. This will always be usable as a key on the feed item instance to fetch that object’s data (i.e. feeditem[feeditem['item_type']] will always be non-null). Can be app, collection, or brand.
order: int - order/weight at which the feed item is displayed on a feed.
resource_url: string - the permanent URL for this feed item.
region: string|null - the slug of a region. If defined, this feed item will only be available in that region.
shelf: object - the full representation of an operator shelf.

List¶

GET /api/v2/feed/items/¶

A listing of feed items.

Response

Parameters:	feed (object) – Listing response meta. shelf (array) – A listing of feed items.

{
    "carrier": null,
    "category": null,
    "collection": 4,
    "region": 1
}

Detail¶

GET /api/v2/feed/items/(int: id)/¶

Detail of a specific feed item.

Request

Parameters:	id (int) – the ID of the feed item.

Response

A representation of the feed item.

Create¶

POST /api/v2/feed/items/¶

Create a feed item.

Request

Parameters:

carrier (int|null) – the ID of a carrier. If defined, it will restrict this feed item to only be viewed by users of this carrier.
category (string|null) – the slug of a category. If defined, it will restrict this feed item to only be viewed by users browsing this category.
region (int|null) – the ID of a region. If defined, it will restrict this feed item to only be viewed in this region.

The following parameters define the object contained by this feed item. Only one may be set on a feed item.

Parameters:	app (int\|null) – the ID of a feed app. collection (int\|null) – the ID of a collection.

{
    "carrier": null,
    "category": null,
    "collection": 4,
    "region": 1
}

Response

A representation of the newly-created feed item.

Status Codes:	201 Created – successfully created. 400 Bad Request – submission error, see the error message in the response body for more detail. 403 Forbidden – not authorized.

Update¶

PATCH /api/v2/feed/items/(int: id)/¶

Update the properties of a feed item.

Request

Parameters:

carrier (int|null) – the ID of a carrier. If defined, it will restrict this feed item to only be viewed by users of this carrier.
category (slug|null) – the slug of a category. If defined, it will restrict this feed item to only be viewed by users browsing this category.
region (int|null) – the ID of a region. If defined, it will restrict this feed item to only be viewed in this region.

The following parameters define the object contained by this feed item. Only one may be set on a feed item.

Parameters:	app (int\|null) – the ID of a feed app. collection (int\|null) – the ID of a collection.

Response

A serialization of the updated feed item.

Status Codes:	200 OK – successfully updated. 400 Bad Request – submission error, see the error message in the response body for more detail. 403 Forbidden – not authorized.

Delete¶

DELETE /api/v2/feed/items/(int: id)/¶

Delete a feed item.

Request

Parameters:	id (int) – the ID of the feed item.

Response

Status Codes:	204 No Content – successfully deleted. 403 Forbidden – not authorized.

Feed Apps¶

A feed app is a thin wrapper around an app, object containing additional metadata related to its feature in the feed. A feed app represents a featured app, a single app that is highlighted on its own in the feed.

Feed apps are represented thusly:

{
    "app": {
        "data": "..."
    },
    "background_color": "#A90000",
    "color": "ruby",
    "description": {
        "en-US": "A featured app",
        "fr": "Une application sélectionnée"
    },
    "type": "icon",
    "background_image": "http://somecdn.com/someimage.png"
    "id": 1
    "preview": null,
    "pullquote_attribute": null,
    "pullquote_rating": null,
    "pullquote_text": null,
    "slug": "app-of-the-month",
    "url": "/api/v2/feed/apps/1/"
}

app: object - the full representation of an app.
background_color: string - background color in 6-digit hex format prepended by a hash. Must be one of #CE001C, #F78813, #00953F, #0099D0, #1E1E9C, #5A197E, #A20D55.
color: string - color code name. The actual color values are defined in the frontend. Currently one of ruby, amber, emerald, topaz, sapphire, amethyst, garnet.
description: string|null - a translated description of the app being featured.
type: string - describes how the feed app will be displayed or featured. Can be icon, image, description, quote, preview.
id: int - the ID of this feed app.
image: string - header graphic or background image
preview: object|null - a featured preview (screenshot or video) of the app.
pullquote_attribute: object|null - a translated attribute of the pull quote.
pullquote_rating: integer|null - a numeric rating of the pull quote between 1 and 5 (inclusive).
pullquote_text: object|null - the translated text of a pull quote to feature with the app
slug: string - a slug to use in URLs for the featured app
url: string|null - the permanent URL for this feed app.

List¶

GET /api/v2/feed/apps/¶

A listing of feed apps.

Response

Parameters:	meta (object) – Listing response meta. objects (array) – A listing of feed apps.

Detail¶

GET /api/v2/feed/apps/(int: id)/¶

Detail of a specific feed app.

Request

Parameters:	id (int) – the ID of the feed app.

Response

A representation of the feed app.

Create¶

POST /api/v2/feed/apps/¶

Create a feed app.

Request

Parameters:

app (int|null) – the ID of a feed app.
background_color (string) – [DEPRECATED] color in six-digit hex (with hash prefix)
color (string) – primary color used to style. Actual hex value defined in frontend.
background_image_upload_url (string) – a URL pointing to an image
description (object|null) – a translated description of the app being featured.
type (string) – can be icon, image, description, quote, or preview.
preview (int|null) – the ID of a preview to feature with the app.
pullquote_attribute (object|null) – a translated attribution of the pull quote.
pullquote_rating (int|null) – a numeric rating of the pull quote between 1 and 5 (inclusive).
pullquote_text (object|null) – the translated text of a pull quote to feature with the app. Required if pullquote_attribute or pullquote_rating are defined.
slug (string) – unique slug to use in URLs for the featured app

{
    "app": 710,
    "background_color": "#A90000",
    "color": "ruby",
    "background_image_upload_url": "http://imgur.com/XXX.jpg",
    "description": {
        "en-US": "A featured app",
        "fr": "Une application sélectionnée"
    },
    "type": "icon",
    "pullquote_rating": 4,
    "pullquote_text": {
        "en-US": "This featured app is excellent.",
        "fr": "Pommes frites"
    },
    "slug": "app-of-the-month"
}

Response

A representation of the newly-created feed app.

Status Codes:	201 Created – successfully created. 400 Bad Request – submission error, see the error message in the response body for more detail. 403 Forbidden – not authorized.

Update¶

PATCH /api/v2/feed/apps/(int: id)/¶

Update the properties of a feed app.

Request

Parameters:

app (int|null) – the ID of a feed app.
background_color (string) – background color in 6-digit hex format prepended by a hash. Must be one of #CE001C, #F78813, #00953F, #0099D0, #1E1E9C, #5A197E, #A20D55.
color (string) – primary color used to style. Actual hex value defined in frontend. Currently one of ruby, amber, emerald, topaz, sapphire, amethyst, garnet.
background_image_upload_url (string) – a URL pointing to an image
description (object|null) – a translated description of the app being featured.
type (string) – can be icon, image, description, quote, or preview.
preview (int|null) – the ID of a preview to feature with the app.
pullquote_attribute (object|null) – a translated attribution of the pull quote.
pullquote_rating (int|null) – a numeric rating of the pull quote between 1 and 5 (inclusive).
pullquote_text (object|null) – the translated text of a pull quote to feature with the app. Required if pullquote_attribute or pullquote_rating are defined.
slug (string) – unique slug to use in URLs for the featured app

Response

A representation of the newly-created feed app.

Status Codes:	200 OK – successfully updated. 400 Bad Request – submission error, see the error message in the response body for more detail. 403 Forbidden – not authorized.

Delete¶

DELETE /api/v2/feed/apps/(int: id)/¶

Delete a feed app.

Request

Parameters:	id (int) – the ID of the feed app.

Response

Status Codes:	204 No Content – successfully deleted. 403 Forbidden – not authorized.

Feed App Image¶

One-to-one background image or header graphic used to display with the feed app.

GET /api/v2/feed/apps/(int:id|string:slug)/image/¶: Get the image for a feed app.

Note

Authentication is optional.

PUT /api/v2/feed/apps/(int:id|string:slug)/image/¶: Set the image for a feed app. Accepts a data URI as the request body containing the image, rather than a JSON object.

Note

Authentication and one of the ‘Collections:Curate’ permission or curator-level access to the feed app are required.

DELETE /api/v2/feed/apps/(int:id|string:slug)/image/¶: Delete the image for a feed app.

Note

Authentication and one of the ‘Collections:Curate’ permission or curator-level access to the feed app are required.

Feed Brands¶

A feed brand is a collection-like object that allows editors to quickly create content without involving localizers by choosing from one of a number of predefined, prelocalized titles.

Feed brands are represented thusly:

{
    'apps': [
        {
            'id': 1
        },
        {
            'id': 2
        }
    ],
    'id': 1,
    'layout': 'grid',
    'slug': 'potato',
    'type': 'hidden-gem',
    'url': '/api/v2/feed/brands/1/'
}

apps: array - a list of serializations of the member apps.
id: int - the ID of this feed brand.
layout: string - a string indicating the way apps should be laid out in the brand’s detail page. One of 'grid' or 'list'.
slug: string - a slug to use in URLs for the feed brand
type: string - a string indicating the title and icon that should be displayed with this feed brand. See a full list of options.
url: string|null - the permanent URL for this feed brand.

List¶

GET /api/v2/feed/brands/¶

A listing of feed brands.

Response

Parameters:	meta (object) – Listing response meta. objects (array) – A listing of feed brands.

Detail¶

GET /api/v2/feed/brands/(int: id)/¶

Detail of a specific feed brand.

Request

Parameters:	id (int) – the ID of the feed brand.

Response

A representation of the feed brand.

Create¶

POST /api/v2/feed/brands/¶

Create a feed brand.

Request

Parameters:	apps (array) – an ordered array of app IDs. layout (string) – string indicating the way apps should be laid out in the brand’s detail page. One of `'grid'` or `'list'`. slug (string) – a slug to use in URLs for the feed brand. type (string) – a string indicating the title and icon that should be displayed with this feed brand. See a full list of options.

{
    "apps": [19, 1, 44],
    "layout": "grid",
    "slug": "facebook-hidden-gem",
    "type": "hidden-gem"
}

Response

A representation of the newly-created feed brand.

Status Codes:	201 Created – successfully created. 400 Bad Request – submission error, see the error message in the response body for more detail. 403 Forbidden – not authorized.

Update¶

PATCH /api/v2/feed/brands/(int: id)/¶

Update the properties of a feed brand.

Request

Parameters:

apps (array) – an ordered array of app IDs. If it is included in PATCH requests, it will delete from the collection all apps not included.
layout (string) – string indicating the way apps should be laid out in the brand’s detail page. One of 'grid' or 'list'.
slug (string) – a slug to use in URLs for the feed brand.
type (string) –
a string indicating the title and icon that should be displayed with this feed brand. See a full list of options.

{
    "layout": "grid",
    "slug": "facebook-hidden-gem",
    "type": "hidden-gem"
}

Response

A representation of the updated feed brand.

Status Codes:	200 OK – successfully updated. 400 Bad Request – submission error, see the error message in the response body for more detail. 403 Forbidden – not authorized.

Delete¶

DELETE /api/v2/feed/brands/(int: id)/¶

Delete a feed brand.

Request

Parameters:	id (int) – the ID of the feed brand.

Response

Status Codes:	204 No Content – successfully deleted. 403 Forbidden – not authorized.

Feed Collections¶

A feed collection is a complex assemblage of apps with a variety of display options.

Apps in feed collections may be grouped. The group they belong to, if set, is represented as a translated group name, which is assigned to the group property of each app’s serialization. If ungrouped, group will be null.

Feed collections are represented thusly:

{
    'apps': [
        {
            'id': 1,
            'group': {
                'en-US': 'Games',
                'fr': 'Jeux'
            },
            ...
        },
        {
            'id': 2,
            'group': {
                'en-US': 'Games',
                'fr': 'Jeux'
            },
            ...
        },
        {
            'id': 3,
            'group': {
                'en-US': 'Tools',
                'fr': 'Outils'
            },
            ...
        }
    ],
    'background_color': '#00AACC',
    'description': {
        'en-US': 'A description of my collection.'
    },
    'id': 19,
    'name': {
        'en-US': 'My awesome collection'
    },
    'slug': 'potato',
    'type': 'promo',
    'url': '/api/v2/feed/collections/1/'
}

apps: array - a list of serializations of the member apps.
background_color: string - background color in 6-digit hex format prepended by a hash. Must be one of #CE001C, #F78813, #00953F, #0099D0, #1E1E9C, #5A197E, #A20D55.
description: object|null a translated description of the collection.
id: int - the ID of this collection.
name: object a translated name of the collection.
slug: string - a slug to use in URLs for the collection
type: string - a string indicating the display type of the collection. Must be one of promo or listing.
url: string|null - the permanent URL for this collection.

When creating or updating a feed collection, the apps parameter may take two forms:

An array of app IDs. This will result in the collection’s apps being ungrouped.

{
    'apps': [1, 18, 3, 111, 98, 231]
}

An array of objects, each with an apps property containing app IDs and a translated name property defining the name of the group for those apps. This will result in the collection’s apps being grouped as specified.

{
    'apps': [
        {
            'apps': [1, 18, 3],
            'name': {
                'en-US': 'Games',
                'fr': 'Jeux'
            }
        },
        {
            'apps': [111, 98, 231],
            'name': {
                'en-US': 'Tools',
                'fr': 'Outils'
            }
        }
    ]
}

List¶

GET /api/v2/feed/collections/¶

A listing of feed collections.

Response

Parameters:	apps (array) – an ordered array of app serializations.. meta (object) – Listing response meta. objects (array) – A listing of feed collections.

Detail¶

GET /api/v2/feed/collections/(int: id)/¶

Detail of a specific feed collection.

Request

Parameters:	id (int) – the ID of the feed collection.

Response

A representation of the feed collection.

Create¶

POST /api/v2/feed/collections/¶

Create a feed collection.

Request

Parameters:

apps – a grouped or ungrouped app list.
background_image_upload_url (string) – a URL pointing to an image
background_color (string) – [DEPRECATED] a hex color used in display of the collection. Currently must be one of #B90000, #FF4E00, #CD6723, #00AACC, #5F9B0A, or #2C393B.
color (string) – primary color used to style. Actual hex value defined in frontend. Currently one of ruby, amber, emerald, topaz, sapphire, amethyst, garnet.
description (object|null) – a translated description of the feed collection.
name (object) – a translated name of the collection.
slug (string) – a slug to use in URLs for the collection.
type (string) – a string indicating the display type of the collection. Must be one of promo or listing.

{
    "apps": [984, 19, 345, 981],
    "background_image_upload_url": "http://imgur.com/XXX.jpg",
    "color": "#B90000",
    "description": {
        "en-US": "A description of my collection."
    },
    "id": 19,
    "name": {
        "en-US": "My awesome collection"
    },
    "slug": "potato",
    "type": "promo"
}

Response

A representation of the newly-created feed collection.

Status Codes:	201 Created – successfully created. 400 Bad Request – submission error, see the error message in the response body for more detail. 403 Forbidden – not authorized.

Update¶

PATCH /api/v2/feed/collections/(int: id)/¶

Update the properties of a collection.

Request

Parameters:

apps (array) – a grouped or ungrouped app list. If included in PATCH requests, it will delete from the collection all apps not included.
background_image_upload_url (string) – a URL pointing to an image
background_color – [DEPRECATED] a hex color used in display of the collection. Currently must be one of #B90000, #FF4E00, #CD6723, #00AACC, #5F9B0A, or #2C393B.
color (string) – primary color used to style. Actual hex value defined in frontend. Currently one of ruby, amber, emerald, topaz, sapphire, amethyst, garnet.
description (object|null) – a translated description of the feed collection.
name (object) – a translated name of the collection.
slug (string) – a slug to use in URLs for the collection.
type (string) – a string indicating the display type of the collection. Must be one of promo or listing.

{
    "apps": [912, 42, 112],
    "color": "#B90000"
    "background_image_upload_url": "http://imgur.com/XXX.jpg",
    "description": {
        "en-US": "A description of my collection."
    },
    "name": {
        "en-US": "My awesome collection"
    },
    "slug": "potato",
    "type": "promo"
}

Response

A representation of the updated feed collection.

Status Codes:	200 OK – successfully updated. 400 Bad Request – submission error, see the error message in the response body for more detail. 403 Forbidden – not authorized.

Delete¶

DELETE /api/v2/feed/collections/(int: id)/¶

Delete a feed collection.

Request

Parameters:	id (int) – the ID of the feed collection.

Response

Status Codes:	204 No Content – successfully deleted. 403 Forbidden – not authorized.

Operator Shelf¶

An operator shelf is a collection-like object that provides a centralized place for operators to showcase content to their customers. They are always bound to category + region pairs, and are only shown to users browsing from the specified category and region.

Operator shelves are represented thusly:

{
    "apps": [
        {
            "id": 1
        },
        {
            "id": 2
        }
    ],
    "background_image": "http://somecdn.com/someimage.png",
    "background_image_landing": "http://somecdn.com/some-other-image.png",
    "carrier": "telefonica",
    "description": {
        "en-US": "A description of my collection."
    },
    "id": 19,
    "is_published": false,
    "name": {
        "en-US": "My awesome collection"
    },
    "region": "br",
    "slug": "potato",
    "url": "/api/v2/feed/shelves/1/"
}

apps: array - a list of serializations of the member apps.
background_image: string - the URL to an image used while displaying the operator shelf.
background_image_landing: string - the URL to an image used while displaying the operator shelf landing page.
carrier: string - the slug of the carrier the operator shelf belongs to.
description: string|null - a translated description of the operator shelf.
id: int - the ID of this operator shelf.
is_published: boolean - whether the shelf is published on a feed in its carrier/region.
name: string - a translated name for the operator shelf.
region: string - the slug of the region the operator shelf belongs to.
slug: string - a slug to use in URLs for the operator shelf
url: string|null - the permanent URL for the operator shelf.

List¶

GET /api/v2/feed/shelves/¶

A listing of operator shelves.

Response

Parameters:	meta (object) – Listing response meta. objects (array) – A listing of operator shelves.

List User’s¶

GET /api/v2/account/shelves/¶

A listing of operator shelves upon which the authenticating user has permission to administer.

Response

A listing of :ref:`operator shelves: <feed-shelves>`.

Detail¶

GET /api/v2/feed/shelves/(int:id|string:slug)/¶

Detail of a specific operator shelf.

Request

Parameters:	id (int) – the ID of the operator shelf.

Response

A representation of the operator shelf.

Create¶

POST /api/v2/feed/shelves/¶

Create an operator shelf.

Request

Parameters:

apps (array) – an ordered array of app IDs.
background_image_upload_url (string) – a URL pointing to an image
background_image_landing_upload_url (string) – a URL pointing to an image
carrier (string) – the slug of a carrier.
description (object|null) – a translated description of the app being featured.
name (object) – a translated name of the collection.
region (string) – the slug of a region.
slug (string) – a slug to use in URLs for the operator shelf.

{
    "apps": [19, 1, 44],
    "background_image_upload_url": "http://imgur.com/XXX.jpg",
    "background_image_landing_upload_url": "http://imgur.com/YYY.jpg",
    "carrier": "telefonica",
    "description": {
        "en-US": "A list of Telefonica's Favorite apps."
    },
    "name": {
        "en-US": "Telefonica's Favorite Apps"
    },
    "region": "br",
    "slug": "telefonica-brazil-shelf"
}

Response

A representation of the newly-created operator shelf.

Status Codes:	201 Created – successfully created. 400 Bad Request – submission error, see the error message in the response body for more detail. 403 Forbidden – not authorized.

Update¶

PATCH /api/v2/feed/shelves/(int:id|string:slug)/¶

Update the properties of an operator shelf.

Request

Parameters:

apps (array) – an ordered array of app IDs.
background_image_upload_url (string) – a URL pointing to an image
background_image_landing_upload_url (string) – a URL pointing to an image
carrier (string) – the slug of a carrier.
description (object|null) – a translated description of the app being featured.
name (object) – a translated name of the collection.
region (string) – the slug of a region.
slug (string) – a slug to use in URLs for the operator shelf.

{
    "apps": [19, 1, 44],
    "background_image_upload_url": "http://imgur.com/XXX.jpg",
    "background_image_landing_upload_url": "http://imgur.com/YYY.jpg",
    "carrier": "telefonica",
    "description": {
        "en-US": "A list of Telefonica's Favorite apps."
    },
    "name": {
        "en-US": "Telefonica's Favorite Apps"
    },
    "region": "br",
    "slug": "telefonica-brazil-shelf"
}

Response

A representation of the updated operator shelf.

Status Codes:	200 OK – successfully updated. 400 Bad Request – submission error, see the error message in the response body for more detail. 403 Forbidden – not authorized.

Delete¶

DELETE /api/v2/feed/shelves/(int:id|string:slug)/¶

Delete an operator shelf.

Request

Parameters:	id (int) – the ID of the operator shelf.

Response

Status Codes:	204 No Content – successfully deleted. 403 Forbidden – not authorized.

Image¶

One-to-one background image or header graphic used to display with the operator shelf.

GET /api/v2/feed/shelves/(int:id|string:slug)/image/¶: Get the image for an operator shelf.

PUT /api/v2/feed/shelves/(int:id|string:slug)/image/¶: Set the image for an operator shelf. Accepts a data URI as the request body containing the image, rather than a JSON object.

DELETE /api/v2/feed/shelves/(int:id|string:slug)/image/¶: Delete the image for an operator shelf.

Builder¶

PUT /api/v2/feed/builder/¶

Sets feeds by region. For each region passed in, the builder will delete all of the carrier-less feed items for that region and then batch create feed items in the order that feed element IDs are passed in for that region.

Request

{
    'us': [
        ['collection', 52],
        ['app', 36],
        ['brand, 123],
        ['app', 66]
    ],
    'cn': [
        ['app', 36],
        ['collection', 52],
        ['brand', 2313]
        ['brand, 123],
    ],
    'hu': [],  // Passing in an empty array will empty that feed.
}

The keys of the request are region slugs.
The region slugs point to two-element arrays.
The first element of the array is the item type. It can be

app, collection, or brand.
The second element of the array is the ID of a feed element.
It can be the ID of a FeedApp, or

FeedBrand.
Order matters.

Response

Status Codes:	201 Created – success. 400 Bad Request – bad request. 403 Forbidden – not authorized.

Feed Element Search¶

GET /api/v2/feed/elements/search?q=(str: q)¶

Search for feed elements given a search parameter.

Request

Parameters:	q (str) – searches names and slugs

Response

Parameters:	apps (array) – feed apps brands (array) – feed brands collections (array) – feed collections shelves (array) – feed shelves

{
    "apps": [
        {
            "id": 343,
            ...
        },
    ],
    "brands": [
        {
            "id": 143,
            ...
        },
    ],
    "collections": [
        {
            "id": 543,
            ...
        },
    ],
    "shelves": [
        {
            "id": 643,
            ...
        },
    ],
}