API Documentation

In This Chapter

Getting started
Using the API
The Nifty API PHP5 client library
The Actions

Nifty has an API (Application Programming Interface) that you can use to build your own applications around our service. With it, you can build your own wish list service, using the power and stability of the Nifty platform. The Nifty API provides methods for getting and setting categories, items, comments, and other data, offered as XML or JSON. More methods will be added as the platform matures. The API is used by our own site, so I know it will work for yours, too!

Nifty started out as a facebook application, before breaking out on its own as a standalone web site in 2009. Just as Nifty itself has its origins in facebook, The Nifty API is strongly influenced by the Facebook API. If you have used the facebook API, then many aspects of the Nifty API will seem familiar to you.

Getting started

To access the Nifty API, you will need:

A developer token
A user session
A method for making HTTP requests

Developer Token

Before you can start using the API, you will need a developer token. To get one, go here and sign up. Tokens are not issued automatically - they are manually approved, so be forewarned that it may take time to get approved for a token. Once you have a developer token, you can hard-code it into your application; it does not change. The developer token is used to implement rate limiting, and to monitor traffic coming from your application. For more information about limitations, refer to the Nifty Terms of Service

User Session

To get a user session, you need to send your users to the login page at http://www.niftywishlist.com/auth/login.php, where the user authenticates with their email address and password. If they log in successfully, Nifty sends this user to a URL of your choice, with usersession token in the querystring.

You must provide two variables in the querystring: devtoken and boomerang. The first one, devtoken, is your application developer key that you got here. The second, boomerang, is the URL that the user will be sent to once they are authenticated. Why "boomerang"? Well, the login page is like a boomerang, you throw a user at it, and the login page flings the user back at you when it's done.

For example, you would send your users to this URL:

http://www.niftywishlist.com/auth/login.php?appid=[your dev token]&boomerang=http%3A%2F%2Fwww.example.com%2Ffinished_login.php

When the user has finished logging in, they will be redirected to a page like this:

http://www.example.com/finished_login.php?usersession=a1a1a1a1a1a1a1a1a1a1a1a1a1

And you, the developer, can have some scripting in the "finished_login.php" page that retrieves the usersession from the querystring. In PHP, this is as simple as reading the value of $_GET['usersession'].

Using the API

The Nifty API is accessible using plain HTTP requests, using either GET or POST. The request is a querystring-escaped collection of variables. You must send an action, the parameters for that action, and four other variables used to establish authentication credentials and data access permission.

Variables Recognized in an API Request

Table 1-30

Actions

Variable	Description
action	this is a procedure call in the form of "noun.verb" and must be one of the actions defined below
params	this is a url-encoded querystring containing the parameters for this action.
microtime	the number of milliseconds elapsed since 1970. Easily generated by the PHP function microtime()
devtoken	This is the token you were issued when you signed up for the developer license.
usersession	session token returned by nifty when the user logs in. To get a session token, you need to send your user to the login page, as described here.
sig	This is a hash used to verify your dev token using your secret developer key, and block repetitive requests. It is calculated using this formula: `$sig = MD5($devtoken . $devsecret . $action . $params . $usersession . $microtime);`
format	optional. This can be "xml" or "json". If omitted, default is XML.

Example

Request

http://www.niftywishlist.com/api/?action=category.get&params=categoryid%3D4095&microtime=123550889207&devtoken=1234567890&usersession=ed8543db92d24dc250940fbffcca4760&sig=b55682981a008b03e473711926c4d238&format=xml

Response

<?xml version="1.0"?>
<!DOCTYPE category SYSTEM "nifty.dtd">
<category id="4095" isdefault="true">
	<name>
		<![CDATA[333444]]>
	</name>
	<items>
		<item id="12851">
			<itemname>
				<![CDATA[MGMT - Oracular Spectacular]]>
			</itemname>
			<description/>
			<currency>pound</currency>
			<currencysymbol>£</currencysymbol>
			<price/>
			<thumburl>
				<![CDATA[http://www.niftywishlist.com/phpthumb/phpthumb.jpg?src=http%3A%2F%2Fle-mode.com%2Fwordpress%2Fwp-content%2Fuploads%2F2008%2F12%2Fmgmt1.jpg&w=50]]>
			</thumburl>
			<link>
				<![CDATA[http://niftywishlist.com/redir.php?id=12851]]>
			</link>
			<comments/>
		</item>
		<item id="12850">
			<itemname>
				<![CDATA[kill a watt]]>
			</itemname>
			<description/>
			<currency>dollar</currency>
			<currencysymbol>$</currencysymbol>
			<price/>
			<thumburl>
				<![CDATA[http://www.niftywishlist.com/phpthumb/phpthumb.jpg?src=http%3A%2F%2Fecx.images-amazon.com%2Fimages%2FI%2F11SD37G6Y8L._SL500_AA150_.jpg&w=50]]>
			</thumburl>
			<link>
				<![CDATA[http://niftywishlist.com/redir.php?id=12850]]>
			</link>
			<comments>
				<comment id="118">
					<userid>3731</userid>
					<commenttext>test test</commenttext>
					<datetime>2009-02-24 09:33:04</datetime>
				</comment>
				<comment id="117">
					<userid>3731</userid>
					<commenttext>test</commenttext>
					<datetime>2009-02-24 09:32:05</datetime>
				</comment>
			</comments>
		</item>
	</items>
</category>

The Nifty API Client library

I've written an API client for PHP5. To install it:

Download the Nifty API client library from here.
Extract the ZIP. Put the files on your server, in a folder named /nifty_api_client/
Edit the config settings in index.php

The API client simplifies requests to the Nifty API by constructing the HTTP request with microtime, devtoken, usersession, and sig. It fills in the authentication credentials and makes the request to the Nifty API. All you need to do is send a request to the client with the action and parameters - and the parameters are in simple name=value pairs in the request querystring.

Example

You would make a request to the API Client, like this:

http://www.example.com/nifty_api_client/?action=category.get&categoryid=5555

This will construct a request to the Nifty API that looks like this: http://www.niftywishlist.com/api/?action=category.get &params=categoryid%3D5555 &microtime=123456789 &usersession=a1a1a1a1a1a1a1a1a1a1a1a1 &devtoken=b2b2b2b2b2b2b2b2b2 &sig=c3c3c3c3c3c3c3c3c3c3

Since the URL being requested is on your domain (example.com), it circumvents cross-domain security problems inherent in AJAX applications. The API Client becomes your very own Cross Domain Proxy. Learn about cross-domain proxies

Configuring the client library

When you unzip the API Client Library, the code in index.php looks like this:

include("nifty_api_client.class");
$api_client = new nifty_api_client();

// we take care of dev authentication in this file, so it doesn't get exposed to the client
$api_client->devtoken = "[your token goes here]";
$api_client->devsecret = "[your secret string goes here]";
$api_client->usersession = "[user session token goes here]";

$api_client->makeRequest();

First, you create an instance of the nifty_api_client class. All the crazy complicated stuff happens in that class, so you don't have to worry about it. Once the $api_client exists, there are three variables that it needs: devtoken, devsecret, and usersession. Devtoken and devsecret were assigned to you when you got your developer token. These will not be changing, so they may be hard coded into your application.

Contrarily usersession is unique for every user that uses your application, and for every session by that user - so first your application needs to get this by sending the user to login to Nifty, as described here. When the user has completed their login, they will "boomerang" back to a URL in your domain, with the usersession exposed in the querystring. It's your responsibility to take that string and store it somewhere so that it can be used by the API client.

For example, if you store the user's usersession in a cookie, that line might look like this:

$api_client->usersession = $_COOKIE['usersession'];

The last line of the code calls the makeRequest() method of the class, and uses those three variables to construct the request, call the Nifty API, and return the results.

Security tip
The api client library has a ".class" extension. If your PHP/Apache is not handling that extension properly, you could be exposing the raw source code to anyone who cares enough to look at it. Since your developer token and secret string are likely to be hard-coded in that file, letting other people see it is not a good thing. Be sure to modify your server config so that it either parses ".class" files with PHP, or protects the folder where the class file resides. This can be accomplished by adding this line to your .htaccess file: AddType application/x-httpd-php .class

The Actions

Table 1-2

Actions

Action	Description
item.get	gets an item
item.put	create a new item
item.delete	delete an item
item.post	edit the properties of an item
category.get	gets a category
category.put	creates a new, empty category
category.delete	deletes a category. any items in this category are moved into the default category
category.post	edit the properties of a category
list.get	gets all categories
comment.get	gets a comment
comment.put	creates a new comment
comment.delete	delete a comment
friendship.get	check if a friendship exists, and its status
friendship.put	add a friend
friendship.delete	remove a friend
registry.post	tell someone that you have purchased an item
session.refresh	refreshes your session so it doesn't expire

back to index

item.get

item.get retrieves a single item from the API

Request Parameters

Table 1-3

Request Parameters for item.get

Parameter	Type	Description
itemid	integer	returns a list , which contains categories and items.

Response Elements

Table 1-4

Response Elements from item.get

Element	Type	Description
itemname	string	name of the item
description	string
currency	string
currencysymbol	string
price	string
thumburl	string
link	string
categoryid	string
categoryname	string

back to index

item.put

Request Parameters

Table 1-5

Request Parameters for item.put

Parameter	Type	Description
itemname	string	name of the item
description	string
currency	string
currencysymbol	string
price	string
thumburl	string
link	string
categoryid	string

Response Elements

Table 1-6

Response Elements from item.put

Element	Type	Description
itemid	integer	identifier of the newly created item

back to index

item.delete

Request Parameters

Table 1-7

Request Parameters for item.delete

Parameter	Type	Description
itemid	integer	identifier for the item to delete

Response Elements

Table 1-8

Response Elements from item.delete

Element	Type	Description
success	boolean	tells you whether the item was deleted

back to index

item.post

Request Parameters

Table 1-9

Request Parameters for item.post

Parameter	Type	Description
itemid	integer	identifier for the item to edit
itemname	string	name of the item
description	string
currency	string
currencysymbol	string
price	string
thumburl	string
link	string
categoryid	string

Response Elements

Table 1-31

Response Elements from item.post

Element	Type	Description
success	boolean

back to index

category.get

Request Parameters

Table 1-32

Request Parameters for category.get

Parameter	Type	Description
categoryid	integer	identifier of the category to get

Response Elements

Table 1-33

Response Elements from category.get

Element	Type	Description
categoryname	string	name of the category
items	collection	this is a collection of items and their properties. the element structure of each item is the same as what is returned from item.get

back to index

category.put

Request Parameters

Table 1-34

Request Parameters for category.put

Parameter	Type	Description
categoryname	string
isdefault	boolean	if true, then this new category will become the default category

Response Elements

Table 1-35

Response Elements from category.put

Element	Type	Description
categoryid	integer	identifier of the newly created category

back to index

category.delete

Request Parameters

Table 1-36

Request Parameters for category.delete

Parameter	Type	Description
categoryid	integer

Response Elements

Table 1-37

Response Elements from category.delete

Element	Type	Description
success	boolean

back to index

category.post

Request Parameters

Table 1-38

Request Parameters for category.post

Parameter	Type	Description
categoryid	integer
categoryname	string
isdefault	boolean

Response Elements

Table 1-39

Response Elements from category.post

Element	Type	Description
success	boolean

back to index

list.get

Request Parameters

Table 1-40

Request Parameters for list.get

Parameter	Type	Description
userid	integer	returns a list, which contains categories and items.

Response Elements

Table 1-41

Response Elements from list.get

Element	Type	Description
categories	collection	this is a collection of category elements. the element structure of each category is the same as what is returned by category.get

back to index

comment.put

Request Parameters

Table 1-42

Request Parameters for comment.put

Parameter	Type	Description
itemid	integer	the item being commented upon
commenttext	string	this is the comment itself

Response Elements

Table 1-43

Response Elements from comment.put

Element	Type	Description
success	boolean	tells you whether the comment was added
commentid	integer	insertion id for this comment

back to index

comment.delete

An authenticated user may delete a comment if it was written by themselves, or if the the item being commented on belongs to that user.

Request Parameters

Table 1-44

Request Parameters for comment.delete

Parameter	Type	Description
commentid	integer	identifier for the comment to be deleted

Response Elements

Table 1-45

Response Elements from comment.delete

Element	Type	Description
success	boolean	tells you whether the comment was deleted

back to index

friendship.get

This method returns the status of a friendship between the current authenticated user and a user passed in as a parameter. The response is a "status" code, indicating one of five possible friendship states. These are defined in the table below:

		Authenticated user
	Value	-	No	Yes
userid	-	0	-1	1
	No	-1	-1	-1
	Yes	2	-1	3

Request Parameters

Table 1-46

Request Parameters for friendship.get

Parameter	Type	Description
userid	integer	the userid of the user whose friendship you are testing

Response Elements

Table 1-47

Response Elements from friendship.get

Element

Type

Description

status

integer

one of the following values:

-1	friendship declined, denied or blocked by either party
0	no relationship
1	invitation sent, no reply
2	you have been invited
3	a confirmed friendship

back to index

friendship.put

This method states that the current authenticated user is friends with the user passed in as a parameter. If no invitation has been sent to the friend, one is sent. If one has been sent already, this method does nothing. If the user has received an invitation from the friend, that friendship is confirmed.

Request Parameters

Table 1-48

Request Parameters for friendship.put

Parameter	Type	Description
userid	integer	the user you are making friends with. This sends a friendship request to the person
email	string	email address of someone the authenticated user is friends with. The owner of this address does not have to be a registered nifty user. If someone registers for Nifty using this email address, the friendship request will already be waiting for them to confirm or decline.

Response Elements

Table 1-49

Response Elements from friendship.put

Element	Type	Description
success	boolean	tells you whether the invitation was sent

back to index

friendship.delete

This method states that the current authenticated user is not friends with the user passed in as a parameter. This method does not send any invitations or notices. If a friendship request has been received, this method declines it. If a friendship exists between the users, this method invalidates it.

Request Parameters

Table 1-50

Request Parameters for friendship.delete

Parameter	Type	Description
userid	integer	the person you are not friends with

Response Elements

Table 1-29

Response Elements from friendship.delete

Element	Type	Description
success	boolean	tells you whether the friendship was deleted

back to index

registry.post

This method declares that the authenticated user has purchased an item. Intended for use on a gift registry.

Request Parameters

Table 1-50

Request Parameters for registry.post

Parameter	Type	Description
itemid	integer	the item being purchased
quantity	integer	how many of this item were purchased. Note: passing a negative integer will remove purchases from a registry.

Response Elements

Table 1-29

Response Elements from registry.post

Element	Type	Description
success	boolean	tells you if the purchase was saved OK

back to index

session.refresh

This method merely refreshes the user's session, so it doesn't expire.

Request Parameters

none