nookedbeta

API - Clients

March 31st, 2008

Client APIs

For more general info on what clients and instances are, see our Clients documentation.

Registering a new client

Currently new clients (specific widget / mashup / tools developed by 3rd parties) need to be manually registered via the Add a new client website page.

Registering a new instance

When a new Client Instance is created (for example by cloning an existing widget instance) the instance should register itself with the platform before it starts to make calls on Feed APIs. This initial call is necessary in order for the instance to obtain an Instance ID which can then be used to track requests to feeds from that particular instance.

URL

POST to https://api.nooked.com/v1/clients/<CLIENT_ID>/instances.xml (secure) or POST to http://api.nooked.com/v1/clients/<CLIENT_ID>/instances.xml where

  • <CLIENT_ID> (required) - the GUID of the Client.

Alternate URL (for clients with no POST capability)

GET https://api.nooked.com/v1/clients/<CLIENT_ID>/instances.xml/create (secure) or GET http://api.nooked.com/v1/clients/<CLIENT_ID>/instances.xml/create where

  • <CLIENT_ID> (required) - the GUID of the Client.

Authentication

Login via HTTP Basic Authentication using your active account or pass in the optional 'api_key" parameter to register new client instances.

Request

Send a POST request with the following params:

  • instance[parent_id]=<PARENT_ID> (optional) - the ID of the parent instance (if one exists). A parent instance is the instance which spawned this client instance.
  • instance[external_id]=<EXTERNAL_ID> (optional) - an external, client specific identifier for this instance. This ID would normally be taken from the environment that the client instance is running in. The use of this parameter allows the client owner to later correlate nooked instance IDs presented in statistics or the nooked web UI with some external identifier mechanism. An example of an external ID might be an account number, an email address or a profile number (e.g. Facebook user id).

Response

The platform responds with a 201 Created status code. The body of the response will contain the following XML

<instance><id>5</id></instance>

Example: Registering a new client - successful request

Request:

Http method: POST
URL: https://api.nooked.com/v1/clients/1/instances.xml

Request data:

instance[parent_id]=1

Response Header:

Status: 201 Created

Response Body:

instance data in XML format

<instance><id>5</id></instance>

Example: Registering a new client - incorrectly

Request:

Http method: POST
URL: https://api.nooked.com/v1/clients/1/instances.xml

Request data

instance[parent_id]=9999

Response header

Status: 400 Bad Request

Response body

<?xml version="1.0" encoding="UTF-8"?>
<errors> 
  <error>Parent instance with ID = 9999 does not exists </error>
</errors>

Listing all client instances

A client application 'owner' can access a list of all instances of that client.

URL

https://api.nooked.com/v1/clients/<CLIENT_ID>/instances.xml (secure) or https://api.nooked.com/v1/clients/<CLIENT_ID>/instances.xml (unsecured) where:

  • <CLIENT_ID> is integer client ID of the client you want the data of

Authentication

Login via HTTP Basic Authentication using your active account or pass in the optional 'api_key" parameter to get client's instances list.

Request

Send a HTTP GET request to the URL specified above.

Response

The platform responds with a 200 OK status code. The body of the response will contain the following an XML list of all instances of that client.

Example: Listing all client instances - successful request

Request:

Http method: GET
URL: https://api.nooked.com/v1/clients/1/instances.xml

Request data

no request data needed

Response header

Status: 200 OK

Response body

instances list in XML format 

  <?xml version="1.0" encoding="UTF-8"?>
  <instances>
    <instance>
      <client-id type="integer">2</client-id>
      <created-at type="datetime">2008-04-01T15:00:34Z</created-at>
      <id type="integer">1</id>
      <parent-id type="integer"></parent-id>
      <updated-at type="datetime">2008-04-01T15:00:34Z</updated-at>
      <user-id type="integer">1</user-id>
    </instance>
    <instance>
      <client-id type="integer">2</client-id>
      <created-at type="datetime">2008-04-01T15:14:38Z</created-at>
      <id type="integer">2</id>
      <parent-id type="integer"></parent-id>
      <updated-at type="datetime">2008-04-01T15:14:38Z</updated-at>
      <user-id type="integer">2</user-id>
    </instance>
  </instances>

Example: Listing all client Instances - incorrect request

Request:

Http method: GET
URL: https://api.nooked.com/v1/clients/9999/instances.xml

Request data:

empty

Response Header:

Status: 404 Not Found

Response Body:

<?xml version="1.0" encoding="UTF-8"?>
<errors> 
  <error>Instances not found at this URL. Please check your client ID. </error>
</errors>

Get information on a Client Instance

A client application 'owner' can access detailed information about a particular instance of that client.

URL

https://api.nooked.com/v1/clients/<CLIENT_ID>/instances/<INSTANCE_ID>.xml (secure) or http://api.nooked.com/v1/clients/<CLIENT_ID>/instances/<INSTANCE_ID>.xml (unsecured) where:

  • <INSTANCE_ID> - is an ID of instance you want to check
  • <CLIENT_ID> - is an ID of client to which instance belongs to

Authentication

Login via HTTP Basic Authentication using your active account or pass in the optional 'api_key" parameter to get client's instances list.

Request

Send a HTTP GET request to where <instance_id> is the Instance ID.

Response

The platform responds with a 200 OK status code. The body of the response will contain an XML representation of the instance data

Example: Get information on a client instance - successful request

Request:

Http method: GET
URL: https://api.nooked.com/v1/clients/1/instance/2.xml

Request data

no request data needed

Response header

Status: 200 OK

Response body

instances list in XML format 

  <?xml version="1.0" encoding="UTF-8"?>
  <instance>
    <client-id>2</client-id>
    <created-at type="datetime">2008-04-01T15:00:34Z</created-at>
    <external-id></external-id>
    <id>1</id>
    <parent-id></parent-id>
    <updated-at type="datetime">2008-04-01T15:00:34Z</updated-at>
    <user-id type="integer">1</user-id>
  </instance>

Example: Get information on a client instance - incorrect request

Request

Http method: GET
URL: https://api.nooked.com/v1/clients/1/instance/9999.xml

Request data

-

Response header

Status: 404 Not Found

Response body

  <?xml version="1.0" encoding="UTF-8"?>
  <errors> 
    <error>Instance not found at this URL. Please check your instance and client ID. </error>
  </errors>
Posted by admin Filed in Documentation

Clients

March 21st, 2008

Clients

So what do we do with all this product data that we have in feeds? We make it available via our APIs to internet based clients that need product data. There are many platforms out there for developing and running clients that interact with nooked - simple styled web page widgets, mashups, feed readers, rich client applications, desktop widgets, social network applications and more.

Tracking Clients

One of the key benefits of syndicating your data via the nooked feed platform is that we provide APIs that you can use when developing your clients that help you to track client instances (a single installation of a client). Every nooked Client has a unique identifier and every instance of a nooked client can get a unique identifier

When instances interact with nooked feeds they can supply an instance identifier. (Note: when creating a feed in nooked, the feed owner can specify that clients must supply an instance identifier). The instance identifier in the API requests allows us to track all sorts of interesting statistics about how clients and feeds are behaving. We can show you (the feed or client owner)

  • How clients are being distributed through the internet. When a new client instance is being created, it has to tell the platform what it's 'parent' instance identifier is. This allows us to build a directed tree model of how instances are distributing across the internet. We can show you the 'important' nodes in this graph, the rate of distribution, dormant sections of the graph and much, much more for each client.
  • How clients are interacting with your feeds. Use this to learn more about the third parties that are developing applications that are consuming your feeds.
  • The rate of click throughs and conversions for each entry (item) in your feeds. Cross referenced with client specific reports, you can see which clients are of the greatest commercial benefit.
  • How categories in your feed data are performing. If your feed entries (items) are grouped into categories you can get a higher level view of how your product data is being used.

Note: the feed owner and the client owners may be two completely different nooked users, as long as the feed is shared (see Feed Settings page). The feed owner gets to see all sorts of interesting statistics about how their feed data is being used and each client developer gets to see statistics about how their clients (and individual instances of those clients) are performing. If the same user owns both the feed data and the clients then they get to see both views of what is happening at runtime.

Pull (Read Only) Clients

Clients that only pull from nooked feeds are the simplest type in that they typically only use a small subset of the nooked APIs. For example a simple client may,

  • Use the Instance Registration API to register each new client instance (when it is first created/started)
  • Get an account's AtomPub Service document to discover feeds dynamically
  • Get the feeds in Atom or RSS format, ideally also presenting their instance id in order to facilitate tracking. A variety of filtering options are also available to search feed contents or only get a subset of categories of entries.

Push/Pull (Read-Write) Clients

These clients are the more sophisticated variety. In addition to the use of the APIs commonly used by simple clients advanced clients can do a lot more as nooked is fully AtomPub enabled. Advanced clients can also do things like:

  • Use the Account Creation API to create new a nooked account for the end user
  • Use the Feed (Collection) Creation API to create a public or private feed for the end user
  • Use the Entry APIs to create, read, update or delete (CRUD) entries in feeds owned by the end user.
  • Use the Source APIs to add remote source feeds (Atom or RSS) to a nooked feed (COMING SOON)
  • It may get an account's AtomPub Service document to discover feeds dynamically
  • It may get the feeds in Atom or RSS format, ideally also presenting their instance id in order to facilitate tracking. A variety of filtering options are also available to search feed contents or only get a subset of categories of entries.

How many APIs your client needs to use is really dependent on your use case - if you think something useful is missing let us know via or forums or contact us.

Posted by fergus Filed in Documentation

Alfresco gets nooked

December 13th, 2005

Alfresco joins the thousands of companies using nooked – the RSS marketing solution of choice – keep tabs on this exciting company. Subscribe here

Who are Alfresco ? Alfresco is the leading open source alternative for enterprise content management. It is the first company to bring the power of open source to the enterprise content management market, enabling unprecedented scale and a much lower total cost of ownership than proprietary systems. Founded by a team of content management veterans that includes the co-founder of Documentum, John Newton and former COO of Business Objects, John Powell. Alfresco is based in London. For more information, visit here

Tags:, , ,

Posted by joshea Filed in Blog 0 comments »

BrightWave gets RSS

November 18th, 2005

Brightwave, a really exciting company based out of the UK, is using RSS.

Unlike some others..

Tags:,, ,

Posted by joshea Filed in Blog 0 comments »