On-Demand

ON THIS PAGE          HideON THIS PAGE          Show Description Request Required Request Header Optional Request Header Request URI Base URI Parameter Optional Parameters Request URI Example Response Response Headers Top-Level Properties Response Descriptive Properties Item Descriptive Properties Sample Feed Response

Description

The On-Demand feed allows you to download content items that you have manually placed into your On-Demand queues in AP Newsroom. You are billed for the On-Demand items based on your contract in AP Newsroom, not when downloading the items from the On-Demand feed.

The On-Demand workflow is optional and may be useful in special cases. For example, you normally populate your editorial CMS by API feed calls to your entitlements, but would also like your news editors to find individual pieces of content in AP Newsroom and send them to a designated area of your CMS. In this case, you would make periodic API calls to check your On-Demand queues for any items editors had placed into the queues via AP Newsroom. Content sent by AP Newsroom users to On-Demand queues stays there for seven days.

The On-Demand queue is designed to give you the items that have been placed there just once and only once. When you request the On-Demand feed, items are returned to you in the order they were placed into the queue. Any returned item is immediately removed from the queue, so you will not receive it again (unless an editor adds the same item again at a later time). For example, if there are 25 items in the queue, and you make an On-Demand feed call asking for a page_size of 10, the first call will return the first ten, the second call the second ten and the third call the final five items. Subsequent calls would return no items until a later time when more content is added.

Request

Request URI

• Method: GET

• Initial Feed Request URI (must be URL-encoded):

  https://api.ap.org/media/v[{version}]/content/ondemand?[{optional_parameters}]

 

	Important
	To check for any updates since your previous feed request, you must follow the "next_page" link from the feed response to ensure that the next feed request picks up precisely where the last request left off. This is the only way to ensure that you do not miss any content or receive excessive duplicate files. For more information, see Getting Content Updates Using Next Page Links.

Base URI Parameter

Optional Parameters

• consumer_id. A user-defined identifier for the consumer of this feed; for example, two different client applications that process items in your On-Demand queue. You can use any value you prefer; for example, python_script, prod_agent and so on. Each unique consumer ID will receive every item in your organization's On-Demand queue once. By default (if this parameter is not specified), the API key of the request is used.

• queue. The ID of the desired queue. You can find the queue IDs in the On-Demand Queues section of the configuration dashboard in AP Newsroom. If this parameter is not specified, the content items from the default On-Demand queue are returned.

• page_size. The maximum number of results to return per page. The default is 10 results with a maximum of 100 per page.

Request URI Example

Initial feed request: https://api.ap.org/media/v/content/ondemand

All subsequent feed requests must use the next_page link from the previous feed response.

Response

The On-Demand method returns the standard HTTP status code of "200 - OK" and a feed of content in the JSON format.

Each feed entry includes the content item ID, a requested set of metadata and links to all renditions of the content item (for example, thumbnail, preview and high-resolution versions of a picture).

Response Descriptive Properties

• updated. The date and time (in UTC) when the response was generated.

• current_item_count. The number of items on the current page.

• next_page. A link to the next page of the feed.

   

	Tip
	To check for any updates since your previous request, it is strongly recommended that your client application use the "next_page" link returned in the feed response for the next request. For more information, see Using Next Page Links for Content Updates.

• items. Contains all of the items on this page.

Item Descriptive Properties

• meta. Contains the non-content specific metadata for an item.

  • products. Contains AP products or packages to which the content item belongs.

    • id. The product or package ID.

    • name. The product or package name.

   

	Note
	The "products" property is not returned by default. Use the include parameter to include this property in the response.

Sample Feed Response

This example shows a response to the following request (the API key is supplied in the x-api-key request header):

https://api.ap.org/media/v/content/ondemand

{
  "api_version": "2.0",
  "api_mode": "live",
  "api_build": "2.0.2", 
  "id": "S1KfSHJBX",
  "method": "/content/ondemand.GET",
  "org_name": "My Organization",
  "params": { },
  "data": {
    "updated": "2020-07-02T15:13:26.752Z",
    "current_item_count": 1,
    "next_page": "https://api.ap.org/media/v/content/ondemand?qt=S1KfSHJBX",
    "items": [
      {
        "meta": { },
        "item": {
          // On-Demand content item metadata and download links
        }
      }
    ]
  }
}