Feed APIs

• Getting a feed
  • Example: Correct feed request
  • Example: Incorrect feed request
• Querying a feed
  • Example: Correct feed query request
  • Example: Incorrect feed query request
• Creating feeds/collections
• Example: Correct feed discovery request
• Example: Incorrect feed discovery request
• Deleting feeds
• Example: Correct feed deletion request
• Example: Incorrect feed deletion request

Getting a feed

Once you have discovered the URL of a nooked feed (either via the owning Service document or by some other out of band means) you can request the contents of the feed using a standard HTTP GET request.

All nooked feeds are available in four 'flavors' - JSON, RSS, Atom feeds and full AtomPub collections/feeds. The RSS and Atom feeds are intended to be used by clients who only require read-only access to the most recent feed entries. The AtomPub feed is intended to be used by clients who need to subsequently modify feed entries, or who wish to page through the whole feed.

• Add new feed entries, update feed entries or delete feed entries
• Require the feed entries to be ordered by their last edited timestamp (not their last updated timestamp)
• Access more than the latest page of feed entries. The AtomPub feed element 'first', 'next', 'previous' and 'last' <link> child elements allow a client to do this

URL

The feed variant type can be requested by appending the appropriate extension onto the feed URL - '.json' for JSON, '.rss' for RSS, '.atom' for Atom and '.app' for AtomPub. AtomPub Service documents contain collections that have URLs - these are the AtomPub feed URLs. Every feed also has RSS and Atom feed URLs that provide the same content but in simpler formats. So using the example above the platform exposes three feed URLs for the contents of the 'Our Product Listing' collection.

• http://api.nooked.com/v1/feeds/1-Our-Product-Listing.app
• http://api.nooked.com/v1/feeds/1-Our-Product-Listing.atom
• https://api.nooked.com/v1/feeds/1-Our-Product-Listing.rss (secure)

Note that .app extension for the AtomPub feed format, .atom for the Atom feed format and .rss for the RSS feed format.

Authentication

No Authentication data is required for public feeds. Login via HTTP Basic Authentication using your active account to access your private feeds.

Requests

Send a GET request to the URL. This is a standard AtomPub API. See the section 5.2 of the AtomPub specification for full details.

Responses

Platform responds with a HTTP Status code indicating the success of the request:

• 200 OK - feed was found and returned.
• 403 Forbidden - feed is not public and therefore available to the requesting user.
• 404 Not Found - when the identifier of feed is wrong or feed is private.

Client tracking

To facilitate tracking of requests from clients, the client can add a 'instance_id' parameter with a value set to the Client Instance GUID that was allocated by the platform to the instance when the instance was created. This parameter is optional but wherever possible it should be specified as it enables richer analytics of feed usage.

Example: Getting a feed request - successful request

Request:

Http method: GET
URL: http://api.nooked.com/v1/feeds/1-Our-Product-Listing.rss

Request data:

no request data is required

Response header:

Status: 200 OK

Response body:

feed in RSS format

<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:atom="http://www.w3.org/2005/Atom" version="2.0">
  <channel>
    <title>Our Product Listing Demo</title>
      ....
  </channel>
</rss>

Example: Getting a feed request - incorrect request

Request:

Http method: GET
URL: http://api.nooked.com/v1/feeds/99999-wrong-GUID-in-the-url.rss

Request data:

no data is required

Response header:

Status: 404 Not Found

Response body:

<?xml version="1.0" encoding="UTF-8"?>
<errors> 
  <error>404 Not Found</error>
</errors>

Querying Feeds By Category

A powerful feature of the nooked feed platform is the ability to query a feed for entries in one or more categories. Queries are defined as an extension of the feed URL - no HTTP headers or body content are required. Note: This API is modeled after the Google Data Query API.

Authentication

This API requires HTTP Basic Authentication using existing username / password credentials. Alternatively you can use your nooked API key, passing it in via an optional 'api_key' HTTP request parameter.

Request

Http method: GET

Construct a URL for the feed query as follows:

• Start with the feed/collection URL from the service document
• append '/-'
• append '/{<SCHEME>}<TERM>' - where <SCHEME> is the value of the <category scheme=...> attribute and <TERM> is teh value of the <category term=... attribute. The <TERM> is mandatory - if no scheme is defined for the category then omit the {} and their contents.

NOTE: you may need to URL encode the completed string in order for your http library to parse it properly when sending the GET request. For example, http://www.nooked.com/v1/feeds/5-Ryanair-Bargains-United-Kingdom.app/-/{ryanair:routes}From-Dublin becomes http://www.nooked.com/v1/feeds/5-Ryanair-Bargains-United-Kingdom.app/-/%7Bryanair%3Aroutes%7DFrom-Dublin when URL encoded.

Example: Correct feed query request

TODO

Example: Incorrect feed query request

TODO

Creating a new feed

You can create new (empty) feeds in nooked via an API call.

URL

The URL of your Service document, available from your My Feeds page.

Authentication

This API requires HTTP Basic Authentication using existing username / password credentials. Alternatively you can use your nooked API key, passing it in via an optional 'api_key' HTTP request parameter.

Request

Http method: POST

Send a POST request to the service document URL with the following parameters:

• feed[title_text]=<TITLE> - where '<TITLE>' is the title of the collection (feed) to be created (REQUIRED)
• feed[page_size]=<PAGE_SIZE> - where '<PAGE_SIZE>' is an integer value specifying the number of feed entries that should appear in RSS/Atom feeds (OPTIONAL, defaults to 20)
• feed[sharing]=<0 or 1> - controls whether requests to GET the feed must authenticate. (OPTIONAL). Note: feed modifications (PUT/POST/DELETE HTTP operations always require authentication (OPTIONAL, defaults to 1)
• feed[feed_hit_requires_instance_id]=<0 or 1> - controls whether client/widget instances must specify an instance id when GETting a RSS, Atom feed or AtomPub collection document (OPTIONAL, defaults to 0)
• feed[entry_hit_requires_instance_id]=<0 or 1> - controls whether client/widget instances must specify an instance id when GETting an Atom entry document (OPTIONAL, defaults to 0)

Response header

Status: 201 Created

Response body

The platform responds with the URL of AtomPub Feed (.app format)

Client Tracking

To facilitate tracking of requests from clients, the client can add a 'instance_id' parameter with a value set to the Client Instance GUID that was allocated by the platform to the instance when the instance was created. This parameter is optional but wherever possible it should be specified as it enables richer analytics of feed usage.

Example: Successful request

Request:

Http method: POST
URL: https://api.nooked.com/v1/services.xml

Request data

feed[title_text]=Title API Created

Response header

Status: 201 Created

Response body

https://api.nooked.com/v1/feeds/9-Title-API-Created.app

Example: Incorrect request

Request:

Http method: POST
URL: https://api.nooked.com/v1/services.xml

Request data

• feed[title_text]=trying to create feed when not logged in.

Response header

Status: 403 Forbidden

Response body

Forbidden. You must authenticate using a valid nooked API Key or HTTP Basic Authentication credentials to access this resource.  

Adding a source to a feed

Coming Soon - send a HTTP POST request to the feed sources collection URL

Removing a source from a feed

Coming Soon - Send a HTTP DELETE request to the feed source URL. For HTTP clients that do not support HTTP DELETE (e.g. most modern browsers), you can send a HTTP POST to the same URL with an additional '_method' parameter with a value set to 'delete'

Deleting a feed

You can delete a feed that you own via an API call.

URL

The feed URL (http or https)

Authentication

This API requires HTTP Basic Authentication using existing username/password credentials. Alternatively you can use your nooked API key, passing it in via an optional 'api_key' HTTP request parameter.

Request

Send a HTTP DELETE request to the feed URL. For HTTP clients that do not support HTTP DELETE (e.g. most modern browsers), you can send a HTTP POST to the same URL with an additional '_method' parameter with a value set to 'delete'

NOTE: This is a very destructive operation. The feed and any related logs will be permanently removed!

Responses

The FeedPlatform responds with a 200 OK status code if the collection was deleted

Client tracking

To facilitate tracking of requests from clients, the client can add a instance_id parameter with a value set to the Client Instance GUID that was allocated by the platform to the instance when the instance was created. This parameter is optional but wherever possible it should be specified as it enables richer analytics of feed usage.

Example: Deleting a feed - successful request

Request:

Http method: DELETE
URL: https://api.nooked.com/v1/feeds/9-Title-API-To-Delete.app

Request data:

No data required

Response header

Status: 200 OK

Response body

Example: Deleting a feed - incorrect request

Trying to delete feed when not authorized

Request:

Http method: DELETE
URL: https://api.nooked.com/v1/feeds/9-Title-API-To-Delete.app

Request data

No data required

Response Header:

Status: 403 Forbidden

Response body

Forbidden. You must authenticate using a valid nooked API Key or HTTP Basic Authentication credentials to access this resource.

Feeds

nooked provide a web service that allows internet based client applications such as widgets, social network applications or other websites to access online retailers product data via easy to access feeds. To date, feeds are typically used to syndicate news content but we believe the same formats and protocols are perfectly suited to distribution of product data to widgets. Our feeds allow widgets to get the information they want without having to develop complicated integrations.

Each product ends up becoming a feed entry and all of our feeds are categorized and searchable allowing for reuse of the underlying product data in a variety of use cases. For example, one widgets may want to show only the latest products in a 'Womens Footwear' category while another widget may be require just the latest product offers from a specific retailer.

By tracking all widget interactions with our feeds, we provide very rich feedback and statistics on how your product data is being received and used by your target audience. You can use nooked to measure the performance of your campaigns, determine which widget platform is delivering the best return on investment and determine which categories and products are producing the most leads to your website.

Creating Feeds

Creating a nooked feed is simple - simply go to ourAdd A Feed page (sign in required) and create a feed! Initially it will of course be empty so you need to get your product data into feeds. nooked supports two main ways to do this:

We'll pull the data from your servers.

nooked feeds can poll your servers for product data at scheduled intervals. In our service we refer to these remote product data listings as 'sources'. You can mix as many sources into a single feed as you like - we will aggregate the data from them all into the nooked feed. Or, if you'd prefer, you can create a nooked feed for each remote source - the decision is a matter of style and usually depends on how you want your product data to be accessed by widget clients.

Source Formats

Currently the nooked platform can poll from sources that are available via HTTP. We can pull in data that is in Google Base (Tab Delimited Format), Atom or RSS feed formats. We will be significantly extending the source formats that we natively support and we can on request add specific source formats in order to get data from legacy proprietary data formats (e.g. legacy CSV formats). Just let us know

You push the data to us

We have lots of APIs that your developers can use to push your product data to us.

Our feed APIs are based on the industry standard Atom Publishing Protocol. This is a simple HTTP protocol that allows you to create, modify or delete feed entries (products). As AtomPub allows you to modify individual product entries in our feeds it is usually much more efficient than any bulk update mechanisms. You get to decide which products need to be updated and you can update them as often or infrequently as you like.

By integrating with us via AtomPub you also benifit from investing in supporting a publishing protocol that is also used by Google, Microsoft and many others for their emerging online web services.

For specific large volume integrations, nooked can do the hard work of briding between your systems and our APIs - just contact us and let us know!

Product = Feed Entry

The nooked platform does not enforce any hard constraints on the content of individual feed entries (products). Feed entries can contain plain text, XHTML, XML or any other valid content type. Rich XHTML in feed entries works well if the content is to be viewed by end users as-is. However, you need to consider that the clients that consume your data via our feeds might be very small widgets or full blown web sites.

To allow clients to figure out what to display you will need to markup your product data in your feed entries or clients won't be able to understand how to display your products properly. This can be done in a number of ways. The entry could contain custom XML that the clients know how to parse but a much better solution that will lead to greater reuse of your data is to adapt well a de-facto or official industry standard. Two primary examples of this are Google Data schemas and Microformats. We believe that the Google Base Products schema is the most flexible, simplest and most widely supported way to markup your product data for consumption by widgets.

To get a feel for what your data will look like once hosted by nooked you don't need to look any further than some of the existing feeds that are hosted on our platform. For example, here is an Atom a feed containing products from Amazon UK. It probably doesn't look too pretty in your feed reader but it makes a whole lot more sense to widgets that need structured data. Go ahead, have a look at the source for that page to get a better idea of what data is in there. Here are some quick highlights:

• This is just the first page of the feed. The <feed><link> elements tell widgets where to go to get more relevant product data
• Each product is presented in a <feed><entry> element
• Each product has a title, summary and full description. The description could be text, html or some other XML document type - we don't interfere with it
• Each product has multiple links to related things like thumbnail or full sized images
• Each product is categorized (via <feed><entry><category> elements
• Each product is timestamped and the feed presents the product list sorted by a most-recently-edited-first rule
• Each product contains Google Base schema <price> and <currency> information and information about shipping locations and costs.

As we mention above, this content doesn't look pretty in a regular feed reader but to widget development tools (and widget developers!) this type of structured product data is perfect for pulling into a variety of widget types. The great thing is, you only need to create your feeds once and they can be used by many widgets, displaying different subsets of data in different ways.