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