Groups APIs

• Getting all groups
• Example: Correct Groups list request
• Getting users in a particular group
• Example: Correct group users list request

Getting all groups

Nooked supports Groups of users on our platform - any Nooked users can belong to many groups. The list of groups is made available via API as a paging Atom feed. These Atom feeds will only contain a limited number of results (defaults to 25 for groups). However, if you need more, the Atom feed returned contains elements that point to the URL of the first/last/next/previous pages (also Atom feeds). JSON versions of these feeds are also supported.

The 'alternate' link element in each feed entry links to another Atom feed which contains entries for each member (user) of the group

URL

https://api.nooked.com/v1/groups.atom or https://api.nooked.com/v1/groups.json

Authentication

No authentication data is needed.

Request

Send a GET request to this URL with no parameters:

Response

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

• 200 OK - The body of the response message will contain an Atom or JSON feed.

Getting a list of members of a group

Use the Groups API to get a list of groups (see above) and GET the Atom feed for a particular Group. The entries in the returned feed represent users in the group. Each entry contains a attribute that points to the users public AtomPub Service Document (which in turn contains references to the users feeds).

The list of groups is made available via API as a paging Atom feed. These Atom feeds will only contain a limited number of results (defaults to 25 for groups). However, if you need more, the Atom feed returned contains elements that point to the URL of the first/last/next/previous pages (also Atom feeds)

URL

https://api.nooked.com/v1/groups/1.atom or https://api.nooked.com/v1/groups/1.json

Authentication

No authentication data is needed.

Request

Send a GET request to this URL with no parameters:

Response

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

• 200 OK - The body of the response message will contain an Atom or JSON feed.

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.

Feeds

nooked provide a web service that allows internet based client applications such as widgets, social network applications or other websites to access online retailers product data via easy to access feeds. To date, feeds are typically used to syndicate news content but we believe the same formats and protocols are perfectly suited to distribution of product data to widgets. Our feeds allow widgets to get the information they want without having to develop complicated integrations.

Each product ends up becoming a feed entry and all of our feeds are categorized and searchable allowing for reuse of the underlying product data in a variety of use cases. For example, one widgets may want to show only the latest products in a 'Womens Footwear' category while another widget may be require just the latest product offers from a specific retailer.

By tracking all widget interactions with our feeds, we provide very rich feedback and statistics on how your product data is being received and used by your target audience. You can use nooked to measure the performance of your campaigns, determine which widget platform is delivering the best return on investment and determine which categories and products are producing the most leads to your website.

Creating Feeds

Creating a nooked feed is simple - simply go to ourAdd A Feed page (sign in required) and create a feed! Initially it will of course be empty so you need to get your product data into feeds. nooked supports two main ways to do this:

We'll pull the data from your servers.

nooked feeds can poll your servers for product data at scheduled intervals. In our service we refer to these remote product data listings as 'sources'. You can mix as many sources into a single feed as you like - we will aggregate the data from them all into the nooked feed. Or, if you'd prefer, you can create a nooked feed for each remote source - the decision is a matter of style and usually depends on how you want your product data to be accessed by widget clients.

Source Formats

Currently the nooked platform can poll from sources that are available via HTTP. We can pull in data that is in Google Base (Tab Delimited Format), Atom or RSS feed formats. We will be significantly extending the source formats that we natively support and we can on request add specific source formats in order to get data from legacy proprietary data formats (e.g. legacy CSV formats). Just let us know

You push the data to us

We have lots of APIs that your developers can use to push your product data to us.

Our feed APIs are based on the industry standard Atom Publishing Protocol. This is a simple HTTP protocol that allows you to create, modify or delete feed entries (products). As AtomPub allows you to modify individual product entries in our feeds it is usually much more efficient than any bulk update mechanisms. You get to decide which products need to be updated and you can update them as often or infrequently as you like.

By integrating with us via AtomPub you also benifit from investing in supporting a publishing protocol that is also used by Google, Microsoft and many others for their emerging online web services.

For specific large volume integrations, nooked can do the hard work of briding between your systems and our APIs - just contact us and let us know!

Product = Feed Entry

The nooked platform does not enforce any hard constraints on the content of individual feed entries (products). Feed entries can contain plain text, XHTML, XML or any other valid content type. Rich XHTML in feed entries works well if the content is to be viewed by end users as-is. However, you need to consider that the clients that consume your data via our feeds might be very small widgets or full blown web sites.

To allow clients to figure out what to display you will need to markup your product data in your feed entries or clients won't be able to understand how to display your products properly. This can be done in a number of ways. The entry could contain custom XML that the clients know how to parse but a much better solution that will lead to greater reuse of your data is to adapt well a de-facto or official industry standard. Two primary examples of this are Google Data schemas and Microformats. We believe that the Google Base Products schema is the most flexible, simplest and most widely supported way to markup your product data for consumption by widgets.

To get a feel for what your data will look like once hosted by nooked you don't need to look any further than some of the existing feeds that are hosted on our platform. For example, here is an Atom a feed containing products from Amazon UK. It probably doesn't look too pretty in your feed reader but it makes a whole lot more sense to widgets that need structured data. Go ahead, have a look at the source for that page to get a better idea of what data is in there. Here are some quick highlights:

• This is just the first page of the feed. The <feed><link> elements tell widgets where to go to get more relevant product data
• Each product is presented in a <feed><entry> element
• Each product has a title, summary and full description. The description could be text, html or some other XML document type - we don't interfere with it
• Each product has multiple links to related things like thumbnail or full sized images
• Each product is categorized (via <feed><entry><category> elements
• Each product is timestamped and the feed presents the product list sorted by a most-recently-edited-first rule
• Each product contains Google Base schema <price> and <currency> information and information about shipping locations and costs.

As we mention above, this content doesn't look pretty in a regular feed reader but to widget development tools (and widget developers!) this type of structured product data is perfect for pulling into a variety of widget types. The great thing is, you only need to create your feeds once and they can be used by many widgets, displaying different subsets of data in different ways.

So, what is nooked?

nooked is a standards based API web service for enabling a variety of internet e-commerce scenarios by distributing products, offers and deals between many retailers, publishers and consumers. nooked uses standard feed publication and syndication formats and protocols to deliver content to widgets, social network applications, mashups - basically anything on the internet or in the mobile world.

Merchants, publishers, consumers and nooked

nooked allows merchants to:

• Create, populate and validate product feeds that contain their product data
• Manage and measure the performance and usage of product feeds
• Negotiate and control revenue sharing with publishers

We work with publishers such as widget developers, affiliate marketers and blog owners to:

• Engage with retailers whose product data they wish to promote
• Create widgets to promote/sell products on their site or other sites if the publisher is an affiliate
• Manage and measure the performance of campaigns and individual widgets

Consumers like social network users, blog owners and web site readers don't usually see nooked but they do use us to find and install widgets that deliver product information they are interested in. What's in it for the consumer?

• They get regular notification of offers and deals that are directly relevant to their needs
• The automatically get widget updates from the publishers server
• They can personalise widgets and share them with others, perhaps leading to a small revenue share or credit/discount with the retailer
• They can use the widgets as a form of self-expression, allowing online shopping to be a more social experience than previously possible. Consumers can participate in social shopping via widgets, for example sharing recommendations with their friends through the widget

For each of the 3 main network constituents feed syndication and publishing standards are the primary plumbing mechanism used for communication.

nooked is a scalable feed publishing/syndication platform that can service data to millions of clients (widgets, mashups, readers etc) on the internet. We provide a rich statistics/analytics system that presents the data owner with detailed information regarding the use of their data by clients. Example metrics are click through (CPC), actions (CPA), trends vs industry etc.

APIs

nooked offers standards based APIs to allow ease of publication and syndication of arbritrary data in RSS/Atom formats - de-facto formats for machine readable data. nooked is AtomPub enabled and supports OpenSearch sharing of search results.

At nooked we believe in the utility of simple web service APIs. We provide them for everything in our platform - publishing/syndicating feed data, creating accounts and feeds and getting analytics data. Simple RESTful APIs are key - we don't use complex WSDL/SOAP/WS-* software stacks. Instead you will find a set of RESTful APIs that most internet client languages (Javascript, flash etc.) can talk to with little or no additional library support. Back end systems can talk to it using simple HTTP support built into every scripting language under the sun. We will, in time, be providing more wrapper libraries for most popular languages to interact with our platform.

The Atom Publishing Protocol

The Atom Publishing Protocol (AtomPub) is a recently approved specification that was developed to tackle the problem of updating feeds in a standard way. It is already gaining significant traction from major players such as Google (OpenSocial APIs are AtomPub based), Microsoft (LiveWriter is an AtomPub client), Wordpress (has AtomPub support) and Movable Type (has AtomPub support).

This unique feature of nooked allows online merchants systems to update feed entries (i.e. product data) on a one-by-one basis if they want to. This real-time update capability can be vital for time sensitive product itinerary.

Sources

As well as allowing use of AtomPub to add entries to yout nooked feeds you can also tell your nooked feeds to aggregate content from existing feeds elsewhere on the internet. We call these remote feeds sources. nooked will pull conent from these sources periodically to batch upload and update product data into the nooked feed platform. An important thing to remember is that a single nooked feed can aggregate content from many remote source feeds in addition to also containing entries created or edited via AtomPub APIs. This allows a single nooked feed to act as a 'river of news' (or 'river of products') that can be presented in a variety of ways.

Sources can be merchants or affiliate data files that contain product data via a variety of formats and protocols. RSS and Atom are the norm, accessed via HTTP but we can add support for other formats if required.

Security

nooked support creation of both public world-readable feeds and private user-readable feeds that require authentication in order to be accessed. Access to nooked statistics data related to feed and client usage also requires authentication.

Scalability

Dealing with millions of clients is our business so scaling our service is a task we are always working on. Our platform architecture allows us to scale horizontally by adding more commodity hosts to our server cluster

nooked is also designed to serve feed content in a manner that allows intermediate internet backbone cache servers to serve content when it has not been changed.

Availability

We recognize that uptime for a service like ours is a key measure of utility and dependability. We deploy our platform into an environment that meets the high availability requirements of commercial internet based web services.