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

Sorry, comments are closed for this article.