nookedbeta

APIs

April 8th, 2008

APIs

nooked is primarily a web service that exposes Application Programming Interfaces(APIs) that you can use to build create feeds and clients (widgets, social network applications, mashups) that consume or produce feeds.

The nooked APIs are split into a few categories:

  • Account APIs - programmatically create accounts on nooked in order to create feeds or clients .
  • Feed - programmatically manipulate feeds owned by an account.
  • Entry APIs - programmatically manipulate entries in feeds owned by an account.
  • Client APIs - Used to register new clients and instances of those clients.
  • Actions APIs - Used by merchants to notify the platform of completed actions.
  • Statistics APIs - Used get statistics on feed and client usage and distribution.

API Authentication

nooked APIs that modify resources (e.g. Entry modification APIs) or return private data (e.g. statistics APIs) can be accessed using one of two authentication mechanisms:

  • HTTP Basic Authentication. If you attempt to call APIs with invalid HTTP Basic Authentication credentials nooked will respond with a "403 Unauthorized" response
  • API Key Authentication. This nooked specific alternative allows you to authenticate by specifying an extra 'api_key' parameter in your request URL. Every nooked account has a unique API Key - you can find yours on your My Clients page

The decision on which mechanism to use is very much up to you. Some client platforms don't support HTTP Basic Auth and others do. The advantage of using the API Key for your clients (especially for widgets that can be downloaded and decompiled) is that the client user never finds out what your nooked account username (and password!) is.

If you attempt to call APIs without supplying one of the above mechanisms nooked will respond with a "401 Forbidden" response

API Encryption

All of our APIs are available via both plain HTTP endpoints ('http://api.nooked.com') or encrypted HTTPS endpoints ('https://api.nooked.com'). When developing client applications that send sensitive data to or from the nooked platform you are strongly encouraged to use the HTTPS endpoints whenever possible. Over time we may disable plain HTTP access to some API endpoints, once we are satisfied that doing so will not preclude their use by popular web application platforms such as widget frameworks.

RESTful APIs

We have used Representational State Transfer as the cornerstone for our platform and API development. We even treat sessions as RESTful resources (check out our account creation and session login APIs if you want). You'll also find that our APIs correlate strongly with our website pages - they are really different ways of accessing the same resources - the representations we serve are typically determined by the extension at the end of the URL you use (e.g. .html, .atom, .rss, .xml etc). Some APIs only return representations in one or two formats but we will be working on extending this coverage as needed. For example, serving feeds in JSON format is high on our todo list...

Posted by admin Filed in Documentation

API - Statistics

April 1st, 2008

Statistic APIs

Feed Impressions Statistics

A feed owner can access detailed statistics about the number of impressions (hits) on each Feed within a particular date range via an API call.

URL

https://api.nooked.com/v1/feeds/<FEED_ID>/stats/hits.atom?from=<FROM_DATE>&to=<TO_DATE> (secure) or http://api.nooked.com/v1/feeds/<FEED_ID>/stats/hits.atom?from=<FROM_DATE>&to=<TO_DATE> (unsecured)

Authentication

Login via HTTP Basic Authentication using your active account or pass in the optional 'api_key" parameter to get your feeds' statistics data.

Request

The caller should send a HTTP GET request to this URL where:

  • <FEED_ID> - the Feed ID
  • <FROM_DATE> - the start date in the format YYYY-MM-DD
  • <TO_DATE> - the to date in the format YYYY-MM-DD

Response

The platform responds with a 200 OK status code. The body of the response is an Atom Feed containing an Entry for each date in the range specified. Each entry title is a date and the content of each entry is the number of feed impressions (hits) for that date.

Feed Clicks Statistics

A feed owner can access detailed statistics about the total number of click throughs on entries in a Feed within a particular date range via an API call.

URL

https://api.nooked.com/v1/feeds/<FEED_ID>/stats/clicks.atom?from=<FROM_DATE>&to=<TO_DATE>(secure) or http://api.nooked.com/v1/feeds/<FEED_ID>/stats/clicks.atom?from=<FROM_DATE>&to=<TO_DATE> (unsecured)

Authentication

Login via HTTP Basic Authentication using your active account or pass in the optional 'api_key" parameter to get your feeds' statistics data.

Request

The caller should send a HTTP GET request where:

  • <FEED_ID> - the Feed ID
  • <FROM_DATE> - the start date in the format YYYY-MM-DD
  • <TO_DATE> - the to date in the format YYYY-MM-DD

Response

The platform responds with a 200 OK status code. The body of the response is an Atom Feed containing an Entry for each date in the range specified. Each entry title is a date and the content of each entry is the total number of feed click throughs for that date.

Feed Actions Statistics

A feed owner can access detailed statistics about the total number of actions on entries in a Feed within a particular date range via an API call.

URL

https://api.nooked.com/v1/feeds/<FEED_ID>/stats/actions.atom?from=<FROM_DATE>&to=<TO_DATE> (secure) or http://api.nooked.com/v1/feeds/<FEED_ID>/stats/actions.atom?from=<FROM_DATE>&to=<TO_DATE>

Authentication

Login via HTTP Basic Authentication using your active account or pass in a 'api_key" parameter to get your feeds' statistics data.

Request

The caller should send a HTTP GET request where:

  • <FEED_ID> - the Feed ID
  • <FROM_DATE> - the start date in the format YYYY-MM-DD
  • <TO_DATE> - the to date in the format YYYY-MM-DD

Response

The platform responds with a 200 OK status code. The body of the response is an Atom Feed containing an Entry for each date in the range specified. Each entry title is a date and the content of each entry is the total number of feed actions for that date.

Entry Clicks Statistics

A feed owner can access detailed statistics about the clicks-throughs for each Feed Entry within a particular date range via an API call.

URL

https://api.nooked.com/v1/feeds/<FEED_ID>/entries/<ENTRY_ID>/stats/clicks.atom?from=<FROM_DATE>&to=<TO_DATE> (secure) or http://api.nooked.com/v1/feeds/<FEED_ID>/entries/<ENTRY_ID>/stats/clicks.atom?from=<FROM_DATE>&to=<TO_DATE> (unsecured)

Authentication

Login via HTTP Basic Authentication using your active account or pass in a 'api_key" parameter to get your feeds' statistics data.

Request

The caller should send a HTTP GET request where:

  • <FEED_ID> - the Feed ID
  • <ENTRY_ID> - the Entry ID
  • <FROM_DATE> - the start date in the format YYYY-MM-DD
  • <TO_DATE> - the to date in the format YYYY-MM-DD

Response

The platform responds with a 200 OK status code. The body of the response is an Atom Feed containing an Entry for each date in the range specified. Each entry title is a date and the content of each entry is the number of clicks for that date.

Entry Actions Statistics

A feed owner can access detailed statistics about the actions completed for each Feed Entry within a particular date range via an API call.

URL

http://api.nooked.com/v1/feeds/<FEED_ID>/entries/<ENTRY_ID>/stats/actions.atom?from=<FROM_DATE>&to=<TO_DATE> (secure) or https://api.nooked.com/v1/feeds/<FEED_ID>/entries/<ENTRY_ID>/stats/actions.atom?from=<FROM_DATE>&to=<TO_DATE> (unsecured)

Authentication

Login via HTTP Basic Authentication using your active account to get your feeds' statistics data.

Request

The caller should send a HTTP GET request to where:

  • <FEED_ID> - the Feed ID
  • <ENTRY_ID> - the Entry ID
  • <FROM_DATE> - the start date in the format YYYY-MM-DD
  • <TO_DATE> - the to date in the format YYYY-MM-DD

Response

The platform responds with a 200 OK status code. The body of the response is an Atom Feed containing an Entry for each date in the range specified. Each entry title is a date and the content of each entry is the number of actions for that date.

Posted by admin Filed in Documentation 0 comments »

API - Entries

March 31st, 2008

Entry APIs

nooked feeds contain many entries (or items in RSS terminology). The nooked feed platform supports the AtomPub protocol for working with Feed Entries.

Getting a single feed entry

Every AtomPub feed entry resources can be requested as a separate Atom Entry document.

URL

Every entry in an AtomPub Feed contains a <link> element that has a rel="edit" attribute. The URL in href attribute is the path to the Feed Entry document.

NOTE: the value of <link> href attributes must be resolved relative to any base attributes that exist on parent elements. So if an entry has a <link> href value of 3456-Shiny-Product-X, the <entry> has an xml:base value of entries/ and the feed has an xml:base value of http://api.nooked.com/v1/feeds/12345-ABCDEF/ then the URL is http://api.nooked.com/v1/feeds/12345-ABCDEF/entries/3456-Shiny-Product-X. This method of resolving URLs using xml:base attributes is defined by W3C XML Base Recommendation (referenced by Section 2 of the Atom syndication spec.)

Authentication

No authentication is needed for getting public feeds. Login via HTTP Basic Authentication using your active account to access your private feeds' entries.

Request

Send a HTTP GET to the feed entry URL.

Response

The platform responds with:

  • a 200 OK status code and the Feed document in the requested format.

This is a standard AtomPub API. See the section 5.2 and section 9 of the AtomPub specification for full details.

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 feed entry request - successful request

Request:

Http method: GET
URL: https://api.nooked.com/v1/feeds/10-Your-products-list/entries/123-superb-new-product.entry

Request data:

no request data is needed

Response Header:

Status: 200 OK

Response Body:

Feed entry in ATOM format 

<?xml version="1.0" encoding="UTF-8"?>
  <entry xmlns="http://www.w3.org/2005/Atom" xmlns:app="http://www.w3.org/2007/app" xml:base="http://platform.nooked.com/v1/feeds/10-Tesco/entries/">
    <id>http://www.external-host.com/dealoftheday/</id>
    <title>Your Superb New Product</title>
    <app:edited>2008-03-03T10:00:00Z</app:edited>
    <updated>2008-03-03T10:00:00Z</updated>
    <published>2008-03-03T10:00:00Z</published>
    <link href="123-superb-new-product.entry" rel="edit"/>
    <link href="123-superb-new-product" rel="alternate"/>
    <content type="text">
      Superb new product description or info about sale etc.
    </content>
  </entry>

Example: Getting feed entry request - incorrect request

Request:

Http method: GET
URL: https://api.nooked.com/v1/feeds/10-Your-products-list/entries/999-WRONG-ENTY-IDENTIFIER.entry

Request data

no data is needed

Response header

Status: 404 Not Found

Response body

<?xml version="1.0" encoding="UTF-8"?>
<errors> 
  <error>Entry not found at this URL.</error>
</errors>

Creating a new feed entry

You can create new Feed Entries via API calls.

URL

Use the relevant AtomPub Collection (feed) URL

Authentication

This API Requires HTTP Basic Authentication using existing username/password credentials. Only owner of feed can create new feed entry for it.

Request

Send a HTTP POST request. The body of the request should contain an Atom Entry document.

Response

The platform responds with a 201 CREATED status code and the URL of the created Feed Entry.

This is a standard AtomPub API. See the section 5.3 and section 9 of the AtomPub specification for full details.

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: Creating a new feed entry request - successful request

Request:

Http method: POST
URL: https://api.nooked.com/v1/feeds/Your-products-list.app(secure)

Request data

  <?xml version="1.0" ?>
  <entry xmlns="http://www.w3.org/2005/Atom">
    <title>New title test</title>
    <author><name>The Atom Protocol Exerciser</name></author>
    <id>tag:some_unique_id,2005:65400065412243367513235656314</id>
    <updated>2008-02-13T17:25:00+01:00</updated>
  <link href='http://www.someurl.org/some-id/1'/>
  <summary type='html'>
    Entry summary 
  </summary>
  <content type='xhtml'>
    <p>New entry <b>content</b> and... some more content</p>
  </content>
  </entry>

Response header

Status: 201 Created

Response body

Feed entry in ATOM format

  <entry xml:base="entries/">
    <id>tag:some_unique_id,2005:65400065412243367513235656314</id>
    <title>New title test</title>
    <updated>2008-02-13T16:25:00Z</updated>
    <summary type="html">
      Entry summary 
    </summary>
    <content type="xhtml">
      <div xmlns="http://www.w3.org/1999/xhtml">
        <p>New entry <b>content</b> and... some more content</p>
      </div>
    </content>
  </entry>

Example: Creating a new feed entry request - incorrect request

Request:

Http method: POST
URL: https://api.nooked.com/v1/feeds/FEED-IDENTIFIER-WHICH-DOES-NOT-EXISTS-OR-USER-HAS-NO-PERMISSION-TO-CHANGE.app

Request data

  <?xml version="1.0" ?>
  <entry xmlns="http://www.w3.org/2005/Atom">
    <title>New title test</title>
    <author><name>The Atom Protocol Exerciser</name></author>
    <id>tag:some_unique_id,2005:65400065412243367513235656314</id>
    <updated>2008-02-13T17:25:00+01:00</updated>
  <link href='http://www.someurl.org/some-id/1'/>
  <summary type='html'>
    Entry summary 
  </summary>
  <content type='xhtml'>
    <p>New entry <b>content</b> and... some more content</p>
  </content>
  </entry>

Response header

Status: 404 Not Found

Response body

<?xml version="1.0" encoding="UTF-8"?>
<errors> 
  <error>No Feed found at this URL.</error>
</errors>

Editing a Feed Entry

You can edit an existing Feed Entry. This is normally done by modifying a local copy of the entry and then sending the new representation to the platform.

URL

The URL is the Feed entry document.

Authentication

This API Requires HTTP Basic Authentication using existing username/password credentials. Only owner of feed can update feed entry.

Request

Send the modified Entry document in the body of a HTTP PUT request to the Entry resource 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 'put'

Response

The platform responds with a 200 OK status code and the URL of the updated Feed Entry.

This is a standard AtomPub API. See the section 5.4 and section 9 of the AtomPub specification for full details.

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: Updating feed entry request - successful request

Request:

Http method: PUT
URL: https://api.nooked.com/v1/feeds/Your-products-list/entries/123-superb-new-product.entry

Request data

  <?xml version="1.0" ?>
  <entry xmlns="http://www.w3.org/2005/Atom">
   <title> updated title</title>
   <author> <name>Author of the entry</name></author>
   <updated>2008-02-13T17:25:27+01:00</updated>
   <link href='http://www.someurl.com/new-article' />
   <summary type='html'>New summary text</summary>
   <content type='xhtml'>
     New entry content
   </content>
  </entry>

Response header

Status: 200 OK

Response body

https://api.nooked.com/v1/feeds/Your-products-list/entries/updated-title.entry

Updated feed entry URL:
https://api.nooked.com/v1/feeds/10-Your-products-list/entries/123-superb-new-product.entry

Example: Updating feed entry request - incorrect request

Request:

Http method: PUT
URL: https://api.nooked.com/v1/feeds/10-Your-products-list/entries/WRONG-ENTRY-IDENTIFIER.entry

Request data:

  <?xml version="1.0" ?>
  <entry xmlns="http://www.w3.org/2005/Atom">
   <title> updated title</title>
   <author> <name>Author of the entry</name></author>
   <updated>2008-02-13T17:25:27+01:00</updated>
   <link href='http://www.someurl.com/new-article' />
   <summary type='html'>New summery text</summary>
   <content type='xhtml'>
     New entry content
   </content>
  </entry>

Response header

Status: 404 Not Found

Response body

<?xml version="1.0" encoding="UTF-8"?>
<errors> 
  <error>No feed entry found at this URL.</error>
</errors>

Deleting a feed entry

You can delete entries in feeds via remote API calls.

URL

To delete a feed entry, to the feed entry URL.

Authentication

This API Requires HTTP Basic Authentication using existing username/password credentials. Only owner can delete feed entry.

Request

To delete a Feed Entry, send a HTTP DELETE request to the Feed Entry 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'

Response

The platform responds with a 200 OK status code.

This is a standard AtomPub API. See the section 5.4 and section 9 of the AtomPub specification for full details.

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: Delete feed entry request - successful request

Request:

Http method: DELETE
URL: https://api.nooked.com/v1/feeds/Your-products-list/entries/123-superb-new-product.entry

Request data:

No data needed

Response Header:

Status: 200 OK

Response Body:

Response body is empty

Example: Delete feed entry request - incorrect request

Request:

Http method: POST
URL: https://api.nooked.com/v1/feeds/10-Your-products-list/entries/WRONG-ENTRY-IDENTIFIER.entry

Request data

No data needed

Response header

Status: 404 Not Found

Response body

<?xml version="1.0" encoding="UTF-8"?>
<errors> 
  <error>No feed entry found at this URL.</error>
</errors>
Posted by admin Filed in Documentation

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 three 'flavors' - RSS, Atom and AtomPub enriched 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

  • 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. 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 0 comments »

API - Accounts

March 27th, 2008

Account APIs

Creating an account

New user accounts can be created by sending a HTTP POST request to the platform with details for the new user.

URL

https://api.nooked.com/v1/users.xml

Authentication

No authentication data is needed.

Request

Send a POST request to this URL with the following parameters:

  • user[login]=<LOGIN> - where '<LOGIN>' is the requested user login name (string)
    '<LOGIN>' must be at least 2 characters long
    '<LOGIN>' must be unique
  • user[:password]=<PASSWORD> - where '<PASSWORD>' is the requested user password (string)
    '<PASSWORD>' must be at least 5 characters long
  • user[email]=<EMAIL> - where '<EMAIL>' is the requested user email address (string)
    '<EMAIL>' must be a correctly formatted e-mail address

Response

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

  • 201 Created - The account was successfully created. The body of the response message will contain the API Key generated for this account (for use as an alternative to HTTP Basic Authentication).
  • 400 Bad Request - Account creation failed. The login or email strings may already be in use by another account or some other data is not valid. The body of the response will be an XML message indicating the error condition.

Example: Correct account creation request

Request:

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

Request data:

user[login]=new_login&user[password]=password1234&user[email]=correct.email@nooked.com

Response Header:

Status: 201 Created

Response Body:

empty

Example: Incorrect account creation request

Request:

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

Request data:

user[login]=new_login&user[password]=password1234&user[email]=wrong@email@address

Response Header:

Status: 400 Bad Request

Response Body:

<?xml version="1.0" encoding="UTF-8"?>
<errors> 
  <error>Password is too short (minimum is 5 characters)</error>
</errors>

Discovering feeds/collections

Each nooked account can own many Feeds (or Collections in AtomPub terminology). Each account has a public AtomPub Service document that can be used to browse the list of feeds (collections) associated with that account. When developing a client that needs to dynamically discover the feeds the client should send a HTTP GET request to the appropriate Service document URL. The Feed Platform will return an AtomPub Service Document

URL

The URL of your Service document is available from your My Feeds page. The Service document URL contains this path and also an additional path segment consisting of an ID (an integer), a dash ('-') and your login. For example, a Service document URL might look like 'http://api.nooked.com/v1/services/78-RetailerX'

Authentication

No authentication is needed. Document is available in public.

Request

Send a GET request to this URL.

Responses

The platform responds with a 200 OK status code with the body containing something like the following content:

<?xml version="1.0" encoding="UTF-8"?>
<service xmlns:atom="http://www.w3.org/2005/Atom" xmlns="http://www.w3.org/2007/app">
  <workspace>
    <atom:title>Retailer X's Service Workspace</atom:title>
    <collection href="http://api.nooked.com/v1/feeds/1-Our-Product-Listing.app">
      <atom:title>Our Product Listing</atom:title>
      <accept>application/atom+xml;type=entry</accept>
    </collection>
  </workspace>
</service>

NOTE: The 'Content-Type' header of the HTTP response to GET requests to Service document URLs are 'application/atomsvc+xml' as prescribed in the AtomPub specification. Most internet browsers don't yet have built in support for this content type so you will prompted to download the file if you try to visit it in your browser. The contents of the file are simple XML and can be viewed in any text editor and of course, parsed by client applications!

This is a standard AtomPub API. See the section 5.1 of the AtomPub specification for full details.

Example: Correct feed discovery request

Request:

Http method: GET
URL: http://api.nooked.com/v1/services/<SERVICE_ID> - where <SERVICE_ID> consists of an ID (an integer), a dash ('-') and your login. For example, a Service document URL might look like http://api.nooked.com/v1/services/78-RetailerX

Request data:

no data is needed

Response Header:

Status: 200 OK

Response Body:

<?xml version="1.0" encoding="UTF-8"?>
<service xmlns:atom="http://www.w3.org/2005/Atom" xmlns="http://www.w3.org/2007/app">
  <workspace>
    <atom:title>xiazek's Service Workspace</atom:title>
    <collection href="http://api.nooked.com/v1/feeds/1-demo.app">
      <atom:title>Demo</atom:title>
      <accept>application/atom+xml;type=entry</accept>
    </collection>
  </workspace>
</service>

Example: Incorrect feed discovery request

Request:

Http method: GET
URL: http://api.nooked.com/v1/services/99999

Request data:

empty

Response Header:

Status: 400 Bad Request

Response Body:

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Wrong SERVICE_ID</error>
</errors>
Posted by admin Filed in Documentation 0 comments »