API - Feeds

March 28th, 2008

Feed APIs

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.
Posted by admin Filed in Documentation

Leave a Reply