Rediff Data & Pattern API Definitions

Rediff API is a set of Data and Pattern APIs that you can use in your App. Rediff realizes that it is critical to provide a dependable interface between the App and Rediff’s social platform. To make the developer’s job easier, we provide RESTful Rediff API methods to access information. In addition, we also provide XML response templates from the Rediff API server. These RESTful Rediff API methods allow you to interact with the Rediff API server. The response templates enable you to anticipate the format of the response from the Rediff API server.

note_icon_3.jpg This section documents our recently upgraded API signatures. If you already have an app with API v1.0, get in touch with us directly in case you need support. But we highly recommend that you upgrade to v2.0 as soon as you can

Rediff Data APIs

When a request is made to the Rediff API server, you need to specify certain parameters in the header, which are:

  • The App's Auth key with the variable name X-REDF-AUTHKEY and the callback URL with the variable name X-REDF-REFERER. A combination of these Headers is required to authenticate the App. The App's Auth Key is provided at the time of registration and the callback url is provided by the App Developer also during the time of registration.
  • A token with the variable name X-REDF-UAUTH that is required to authenticate a user and to verify if the user is actually logged in or not.

The remaining headers of the RESTful Rediff API method will change based on the API that is being called.

Rediff groups together APIs based on functionality as:

  • Profile API This set of APIs returns information from the user’s profile. The Profile API consists of the GetProfile API and GetFullProfile API.
  • Friends API This set of APIs returns information about the user’s friends and enables you to invite friends to use an App. The Friends API includes the GetFriends API.
  • Notification API This API allows the App to send email notifications to the user. There are two types of Notification APIs depending on the type of notification to be retreived.

^The list of APIs will grow as they are developed.^

Profile API

The Profile APIs enable you to retrieve user information such as the first name, last name, location, etc.

Getting the user's profile

This API enables you to retrieve user information, such as the first name, last name, location, etc

HTTP Request
Request URL http://www.rediffapi.com/profile/uid#?version=2
HTTP Method GET
Required Headers X-REDF-AUTHKEY, X-REDF-REFERER

note_icon_3.jpgIn the Request URL, you need to specify the user ID for which you want to retrieve information. uid# indicates multiple comma seperated user IDs.

XML Response
Response XML
<?xml version=”1.0” encoding=”UTF-8”?>
	<response>
		<user>
			<firstname></firstname>
			<lastname></lastname>
			<location>
				<city></city>
				<country></country>
			</location>
			<friendcount></friendcount>
			<photolink></photolink>
		</user>
	</response>
Exceptions

Friends API

Getting the user's friends

This API provides you with list of user's friends and basic information about them on Rediff’s social network.

HTTP Request
Request URL http://www.rediffapi.com/user-friends/uid/{pagination}?version=2
HTTP Method GET
Required Headers X-REDF-AUTHKEY, X-REDF-REFERER

note_icon_3.jpgIn the Request URL, you need to specify the number of friends to be retrieved for a specific user ID. This is known as Pagination. The pagination is specified as <start>-<end>, where <start> indicates the start of the result set, and <end> indicates the last record to be returned. For example, if you want to retrieve 5 friends, you need to specify the pagination as 0-5. For the next 5 friends, specify pagination as 6-10

XML Response
Response XML
<?xml version=”1.0” encoding=”UTF-8”?>
		<response>
			<users>
				<usersMeta>
					<startCount></startCount>
					<count></count>
					<totalCount></totalCount>
				</usersMeta>
				<user>
					<userid></userid>
					<firstname></firstname>
					<lastname></lastname>
					<status></status>
					<location>
						<city></city>
						<country></country>
					</location>
				</user> 
				<user></user>
				<user></user>
				<user></user>
			</users>
		</response>
Exceptions

Notification API

These Notification API enables you to reach out to a specific user through email as well. Unlike feeds, notifications are not broadcast and hence can also be used to send messages to the user. The various notification API include:

  • Return a list of notifications for a particular user
  • Return details of specified notification ID
  • Create a notification for a user
  • Update a notification E.g. “mark as read”

Getting a list of notifications for a particular user

This API enables you to get the list of all notifications of the User ID.

HTTP Request
Request URL http://www.rediffapi.com/user-notifications/uid/{pagination}?version=2
HTTP Method GET
Required Headers X-REDF-UID, X-REDF-AUTHKEY, X-REDF-UAUTH, X-REDF-REFERER

note_icon_3.jpgIn the Request URL, you need to specify the number of notifications to be retrieved for a specific user ID. This is known as Pagination. The pagination is specified as <start>-<count>, where <start> indicates the start of the result set, and <count> indicates the number of records to be returned. For example, if you want to retrieve the first 5 notifications for a particular user ID, you need to specify the pagination as 0-5. The HTTP Request will return the first 5 records for the specified user ID. For the next 5 notifications, provide 5-5

XML Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
	<meta>
		<status>{0|1}</status>
		<statusMessage>{Response message (can be blank)}</statusMessage>
		<startingIndex>{As specified in the request XML}</startingIndex>
		<numberOfNotifications>{As specified in the request XML}</numberOfNotifications>
	</meta>
	<notifications>
		<notification>
			<notificationid>{For retrieving notifications (Blank if notification failed)}</notificationid>
			<subject><![CDATA[This is a subject for the notification]]></subject>
			<message><![CDATA[This is the body of the notification (Cannot be HTML)]]></message>
			<notificationType>{alert|request}</notificationType>
		</notification>
		<notification>
			<notificationid>{For retrieving notifications (Blank if notification failed)}</notificationid>
			<subject><![CDATA[This is a subject for the notification]]></subject>
			<message><![CDATA[This is the body of the notification (Cannot be HTML)]]></message>
			<notificationType>{alert|request}</notificationType>
		</notification>
		<notification>
			......
		</notification>
		<notification>
			......
		</notification>
	</notifications>
</response>

Getting details of a specific Notification ID

This API enables you to get the details for a specific notification ID. Typical usage would be to first get the list of user's notifications and then seek the details of each notification. In many cases, you would have saved some details of the notification in your app as well, so just the list o

HTTP Request
Request URL http://www.rediffapi.com/notifications/nid#?version=2
HTTP Method GET
Required Headers X-REDF-UID, X-REDF-AUTHKEY, X-REDF-UAUTH, X-REDF-REFERER

note_icon_3.jpgIn the Request URL, you need to specify the notification ID for which you want to retrieve information. nid# indicates multiple comma seperated notification IDs.

XML Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
	<meta>
		<status>{0|1}</status>
		<statusMessage>{Response message (can be blank)}</statusMessage>
	</meta>
	<notifications>
		<notification>
			<notificationid>{For retrieving notifications (Blank if notification failed)}</notificationid>
			<subject><![CDATA[This is a subject for the notification]]></subject>
			<message><![CDATA[This is the body of the notification (Cannot be HTML)]]></message>
			<notificationType>{alert|request}</notificationType>
		</notification>
		<notification>
			<notificationid>{For retrieving notifications (Blank if notification failed)}</notificationid>
			<subject><![CDATA[This is a subject for the notification]]></subject>
			<message><![CDATA[This is the body of the notification (Cannot be HTML)]]></message>
			<notificationType>{alert|request}</notificationType>
		</notification>
		<notification>
			.......
		</notification>
		<notification>
			.......
		</notification>
	</notifications>
</response>

Creating a Notification

Notifications are messages directed to a specific user (unlike feeds which are broadcast to friends). A notification can be a message, an image, or a video. The user will receive an email in addition to seeing the notification on MyPage. This API can be used with HTTP POST to create a new notification and with HTTP PUT to update a notification e.g. “mark as read”. You would need to update notifications (mark as read) when the user has taken the required action inside your app. E.g. if he responded to a challenge from friend, you can remove the challenge from his list of notifications.

HTTP Request
Response URL http://www.rediffapi.com/notification?version=2
HTTP Method POST
Required Headers X-REDF-UID, X-REDF-AUTHKEY, X-REDF-UAUTH, X-REDF-REFERER
Parameters xml
Request XML
<?xml version="1.0" encoding="UTF-8"?>
	<request>
	<requestinfo>
		<responsestyle>xml</responsestyle>
	</requestinfo>
	<content>
		<requestedaction>sendNotification</requestedaction>
		<notifications>
			<notification>
				<userid>[Receiver's User ID]</userid>
				<subject><![CDATA[This is a subject for the notification]]></subject>
				<message>
					<![CDATA[This is the body of the notification (Cannot be HTML)]]>
				</message>
			</notification>
		</notifications>
	</content>
</request>
XML Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
	<notificationResponse>
		<notification>
			<userid>[Receiver's User ID]</userid>
			<status>{0|1}</status>
			<statusMessage>{Response message (can be blank)}</statusMessage>
			<notificationid>{For retrieving notifications (Blank if notification failed)}</notificationid>
		</notification>
	</notificationResponse>
</response>

Updating a Notification

The PutNotification API enables you to update a notification, such as marking a notification as read.

HTTP Request
Response URL http://www.rediffapi.com/notification?version=2
HTTP Method PUT
Required Headers X-REDF-UID, X-REDF-AUTHKEY, X-REDF-UAUTH, X-REDF-REFERER
Parameters xml
Request XML
<?xml version="1.0" encoding="UTF-8"?>
<request>
	<requestinfo>
		<responsestyle>xml</responsestyle>
	</requestinfo>
	<content>
		<requestedaction>markNotificationAsRead</requestedaction>
		<notifications>
			<notification>
				<userid>[Receiver's User ID]</userid>
				<notificationid><![CDATA[notificationid]]></notificationid>
			</notification>
		</notifications>
	</content>
</request>
XML Response
<?xml version="1.0" encoding="UTF-8"?>
<response>
	<notificationResponse>
		<notification>
			<userid>[Receiver's User ID]</userid>
			<status>{0|1}</status>
			<statusMessage>{Response message (can be blank)}</statusMessage>
			<notificationid>{For retrieving notifications (Blank if notification failed)}</notificationid>
		</notification>
	</notificationResponse>
</response>

Rediff Pattern APIs

To understand what are patterns, please visit the Understanding Patterns page.

A Pattern can be used in two formats, button and javascript. In case of a button format, you will get the HTML button based on the pattern you are using. However, in case of a javascript format, in order to invoke the pattern, you need to call the required function. As an App Developer, you need to set certain variables in the javascript (depending on the pattern). The Request URL will differ depending on the type of format used for a particular Pattern. However, if format is not mentioned in URL then by default js format will be delivered.

There are three types of Rediff Pattern APIs, namely:

  • Invite - This API allows you to quickly incorporate the pattern to invite friends to the app being used.
  • FeedPublish - This API enables you to publish messages to a user’s page. A feed can be a message, an image, or a video.
  • AddFriend - This API allows you to quickly incorporate the pattern to add friends to a user's MyPage account.

Invite Friends

This pattern allows you to quickly incorporate the pattern to Invite friends to the app being used.

For example, if you want to use a pattern, you only need to use the following embed code:

<div id="rediff-pattern-container-for-invite">
	<script type="text/javascript" src="http://www.rediffapi.com/patterns/invite-friend/[APPID]?version=2&format={button/js}"></script>
</div>

However, if you want to use a javascript based pattern, you need to invoke it using the “rediff_pattern_loadinvite()” function.

For example:

<INPUT TYPE="button" VALUE="Invite" ONCLICK="rediff_pattern_loadinvite();">

FeedPublish

Variables to be set in JS FEED_PUBLISH_MSG,FEED_PUBLISH_THUMB_URL,FEED_PUBLISH_BUTTON_TITLE,FEED_PUBLISH_ERR_MESSAGE

In version 2.0, developer *must not* include APP_AUTH_KEY in javascript or anywhere else which is readable to outside world.

For example, if you want to use a pattern, you only need to use the following embed code.

<div id="rediff-pattern-container-for-publisher">
	<script type="text/javascript" src="http://www.rediffapi.com/patterns/feeds/[APPID]?version=2&format={button/js}" ></script>
</div>

However, if you want to use a javascript based pattern, you need to invoke it using the “rediff_pattern_loadpublisher()” function.

For example:

<INPUT TYPE="button" VALUE="Share with your friends!" ONCLICK="rediff_pattern_loadpublisher();">

Required Variables

The following variables need to be declared and set in your Javascript code for the proper execution of the pattern.

       // The message to be published to the feed. If 'null', then the pattern displays the error message defined below.
       var FEED_PUBLISH_MSG = null;
       // The title for the feed. 
       var FEED_PUBLISH_TITLE= null;
       // The URL of the thumbnail associated with the feed message.
       var FEED_PUBLISH_THUMB_URL = null;
       // The title of the button that will invoke the pattern.
       var FEED_PUBLISH_BUTTON_TITLE = "Share Your Mood";
       // The error message to be displayed if the FEED_PUBLISH_MSG variable is not set.
       var FEED_PUBLISH_ERR_MESSAGE = "You need to select your mood before you can share it with your friends";

Add Friends

This pattern allows the developers to quickly incorporate the pattern to Add friends to a user's MyPage account.

For example, if you want to use a pattern, you only need to use the following embed code.

<div id="rediff-pattern-container-for-addition">
        <script type="text/javascript" src="http://www.rediffapi.com/patterns/add-friend?version=2&format={button/js}"></script>
</div>

However, if you want to use a javascript based pattern, you need to invoke it using the “rediff_pattern_loadaddfriend()” function.

For example:

<INPUT TYPE="button" VALUE="Add friend" ONCLICK="rediff_pattern_loadaddfriend();">

CLICK HERE to return to the main Table of Contents.

rediff_api_definitions_version_2.0.txt · Last modified: 2011/02/11 12:19 by Sagar
Back to top
CC Attribution-Noncommercial-Share Alike 3.0 Unported
chimeric.de = chi`s home Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0