nookedbeta

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...