Tagged Partner Integration API

Draft 2011-04-08

This version:
http://www.tagged.com/api/spec.html
Generated on:
2014-12-21T04:44:18-0800
Editors:
Johann Schleier-Smith, CTO, Tagged <johann@tagged.com>
Michael Chen, Senior Software Engineer, Tagged <mchen@tagged.com>
Terry Chat, Architect, Tagged


Abstract

This outlines the ways at which partners are able to integrate with the Tagged network.

Status of this Document

This section describes the status of this document at the time of its publication.

This document is an outline of how ‘widgets’ and some photo access calls will be supported between Tagged and the partners.

There is a changelist to this document available at the end of the document

Table of Contents

Appendices

A ChangeLog


1 Introduction

Web 2.0 is a catchall description for a lot of ideas that describe modern consumer facing websites, it includes things like social networking, mashups, AJAX design patterns, etc.Tagged is a social networking platform. A good platform is one that works with partners to enable them to integrate with it.

This document specifies such integration points.

1.1 Origin and Goals

A mashupable web service is more than just generating an API and expecting the world to figure a use for it. What is really needed is one that addresses real needs of our users in a manner that makes it both easy and seamless for partners to support.

The current goals are:

  1. To enable partner integration through API service.

  2. Allow partners to develop seamlessly integrated games and applications on Tagged.

  3. Document the Photos API, Friends API, About Me API, Message API and Test API available to partners.

1.2 Terminology

A description of terms used in this document

Box

An user-created section of a Tagged User’s Profile Page. A box consists of a title, caption, and content which may be a Widget.

Profile Page

The user’s profile on the Tagged Website. (Example.)

Tagged User

A user who is currently logged in to the Tagged Website.

Widget

A Widget is a reserved area in the Profile Page that allows for the inclusion of Partner Components. All widget requests are marshalled through the User’s client browser.

Widget Protocol

The action that occurs when the creation of a Widget is initated on the Tagged Website by a Tagged User. All widget requests are marshalled through the User’s client browser.

2 Protocols

Currently the only request protocol supported is HTTP POST. The only request payload is a url encoded string (post URL).

There are only three return protocols supported:

  • Calls to the Application Callback URL done as a Widget call are HTTP GET URL encoded string done by the user client browser (standard HTTP GET request).
  • Calls to the Application Callback URL for HTTP POST URL encoded string done by the Tagged Website (standard HTTP POST form post).
  • All other API calls from the Partner Site to the Tagged Website are returned in JSON format. (XML will be supported shortly.)

All data should be UTF-8 encoded.

2.1 Signing a request

Various API functions may require or optionally encode a signature of the request in order to validate the identity of the requesting service.

Signing with the secret obeys the same convention of many Web-based mashups. The procedure to sign a request is as follows

  1. Sort the argument list of the request in alphabestical order based on the parameter name.
  2. Concatenate the shared secret and the argument name-value pairs.
  3. Calculate the md5 sum of this string as a hexidecimal string.
  4. Append this value to the argument list with the name api_signature.

Let us say secret is: 9ed8905b4e55fff3 and the request looks like foo=1, atest=2, bar=3

  1. The new order is atest=2, bar=3, foo=1.
  2. The string is: 9ed8905b4e55fff3atest2bar3foo1.
  3. The md5 sum is: 598a77fbd7130d4335d2a4c3272c7990.
  4. The querystring will be ?foo=1&atest=2&bar=3&api_signature=598a77fbd7130d4335d2a4c3272c7990.

2.2 Widget content payload

When a widget is created there are certain restrictions on the html content. This part of the document outlines this.

Widget content may not be transformed to larger than 3500 bytes in UTF-8.

Widget content will be filtered on the server side. A webpage will be put up that will allow partners to test html snippets for transformaiton and report bugs on the system.

3 Use Cases

This section outlines various use cases where the API might access.

3.1 Tagged Widget

The widget case is where the Tagged User intitiates the Integration with a Business Partner from a Feature on the Tagged Website.

Some typical examples:

  • Tagged User wishes to create a new Box with a widget in it. Example.

  • Tagged User wishes to add a widget to a Box on the their Profile Page.

  • Tagged User wishes to add a widget to the About Me section on their Profile Page

  • Tagged User wishes to add a widget their Wall on their Profile Page

3.1.1 Tagged Widget Flow

  1. Tagged User selects a widget on the Tagged Website by clicking on a link.

  2. Tagged User issues a Widget Referral Request to the Partner Website through their client.

  3. The Partner Website may interact with the Tagged Website via the Tagged User API. Note that authentication as the user on Taggeds site has already been done which provides limited features based on the partner. For instance, a partner may want to get a list of a users photos with tagged.photo.list.

  4. The User interacts with the Partner Website to create the widget content. This is handled by partner.

  5. When widget needs to be created by the partner, the Tagged User, by clicking on the Partner Website, will issue a Widget Return Request onto the Tagged Website.

3.2 Application-initiated Widget

Application partner creates a new widget via using a Users client browser to authenticate the creation.

Typically this is done by “web scraping’. This is not desiged for a number of reasons

  • It requires a Tagged User to authenticate twice.
  • It requires the user cede their Tagged user and password to a 3rd party website.
  • It gives the user no control of the access level the 3rd party website has.
  • It is a lot of work for the 3rd party site to write.
  • It is fragile to changes to the Tagged Website.
  • It is fragile to changes in the password.
  • It requires the 3rd party site to maintain attache these credentials for future requests.
  • It provides no audit trail on the application.
  • It has no possibility of editing the widget at a future date.
  • It is limited only those actions the user can do on the Tagged Website. For instance, for widgets, they’d be restricted to only Business Partner widgets.

Some typical examples:

  • User clicks on an “Add to Tagged” link on Application Partner website.

3.2.1 Application-initiated API access

  1. Partner site wishes to access data from Tagged's website.

  2. Partner redirects user to Tagged website.

  3. If User is not a Tagged User, they are presented with a login screen and becomes a Tagged User.

  4. User is presented with a screen asking them to authorize the third party site for access to their Tagged User data..

  5. Tagged User issues a Widget Referral Request to the Partner Website through a client redirect. Partner makes API calls on Tagged Website via the API.

3.2.2 Application-initiated Widget Flow

  1. User creates content on Application Partner website and clicks on an link to the Widget Authorization Request URL.

  2. If User is not a Tagged User, they are presented with a login screen and becomes a Tagged User

  3. User is presented with a screen on the Tagged Website which asks them where they would like to place the Widget or to create a Box.

  4. Tagged User issues a modified Widget Referral Request to the Partner Website through their client. Flow continues as if the Application Partner is a Business Partner doing a standard Tagged Widget flow, skipping the first step.

4 API Calls

This section explains the API location, inputs and outputs of the access requests

4.1 Widget

Note that some flows in this API are only available to Business Partners.

4.1.1 The Widget Referral Request

This API is only supported for Business Partners.

The protocol for this is an HTTP GET sent by the Tagged User directly to the Application Callback URL which is provided by the Business Partner and stored on Tagged’s server linked to the AppID.

4.1.1.1 Reserved GET parameters

Tagged will cause the user to provide a number of parameters to assist in the Widget creation on the Partner Website.

NameExample dataTypeDescription
application_idapp-partnerStringThe the identifier for the Partner’s Application as registered with Tagged. In some cases this is an ignorable field: If the Business Partner has only one Application registered with Tagged or if the Partner specifies a different Application Callback URL for each Application then this value is moot.
session_tokendee0faeb184a937190d7af885b57bbfaStringThis provides authentication for the Widget Return Request. It also identifies the particular widget on Tagged’s servers. Note that this will only be live for 30 minutes after the last request.
user_id18347282StringThis field is ignorable. It is used if the Partner wants to link accounts, make future API calls, etc. It is therefore permitted for the Partner to store this.
max_width278NumberThis is the maximum embed width in pixels. The values Tagged currently sends are currently 278, 440 and 720. In a future release this will be upped to 280, 450, 740.
max_height-1NumberThis is the maximum embed height in pixels. If -1, then there is no vertical maximum size which is the only value sent in the current version of the API.
tag_featureboxStringThis hints to the the Business Partner on part of the site the Tagged User intends to put the widget. The Business Partner may want to present a different feature set based on this.
tag_echoStringCurrently this will be used by the Tagged for other data payload and should just be returned to the Tagged Website in a Widget Return Request.
api_signature2e4d33fa86f600d218640262e6de2008StringThis is the API Signature of the request made. The partner may ignore this or can use this to verify that the request was actually generated by a Tagged Server and not faked.

In the above example, the URL called will be:

http://www.partner.com/partner/tagged_entry?application_id=app-partner&session_token=dee0faeb184a937190d7af885b57bbfa&user_id=278&max_width=-1&max_height=box&tag_echo=&api_sig=2e4d33fa86f600d218640262e6de2008

4.1.2 The Widget Return Request

The protocol for this is an HTTP POST sent by the Tagged User directly to the http://www.tagged.com/api/widget/return/. After this the user will be redirected back to the page they left with the widget created.

4.1.2.1 Expected POST parameters

Tagged expects a number of parameters in the request.

NameExample dataTypeDescription
application_idapp-partnerStringThe the identifier for the Partner’s Application as registered with Tagged.
session_tokendee0faeb184a937190d7af885b57bbfaStringThis identifies which widget to allow injection of the content into. This was provided in the Widget Referral Request.
widget_content<img src="http://x.tagstat.com/im/app/photo_widget.jpg" />StringThis is the HTML payload (embed content) to inject as the widget in the site. The payload is transformed on the server side as outlined above.
tag_echoStringThis was provided in the Widget Referral Request.
api_signaturecfcb13a0306a4a79e1dc57fe1a5f72aeStringThis is the API Signature for the request made. In this version of the spec, this is not required for this call, but this may change later.

4.1.3 The API Authorization Request

The protocol for this is an HTTP POST (or GET) esent by the Tagged User directly when redirected to https://www.tagged.com/api/access/. The return for this is to identical to the return of the Widget Referral Request except the widget fields should be ignored.

4.1.3.1 Expected GET or POST parameters

Tagged expects a number of parameters in the request.

NameExample dataTypeDescription
application_idapp-partnerStringThe the identifier for the Partner’s Application as registered with Tagged.
4.1.3.1 Returned POST parameters

The return looks identical to the API Widget Referral Request except the widget-related fields should be ignored.

4.1.4 The Widget Authorization Request

The protocol for this is an HTTP POST sent by the Tagged User directly to the http://www.tagged.com/api/widget/auth/. The return for this is to identical to the return of the Widget Referral Request except for extra data that is mentioned below, and the data is put in an HTTP POST instead of a GET.

4.1.4.1 Expected POST parameters

Tagged expects a number of parameters in the request.

NameExample dataTypeDescription
application_idapp-partnerStringThe the identifier for the Partner’s Application as registered with Tagged.
app_echoa:1:{s:9:"PHPSESSID";s:32:"a17912534863c97a996915a384a9c6eb";}StringThis data will be echoed in the return and can be used by the Application Partner to store state information.
api_signature1b1e1d407e749706061af4e329d79fa2StringThis is the API Signature for the request made. In this version of the spec, this is not required for this call, but this may change later.
4.1.4.1 Returned POST parameters

The return looks identical to the API Widget Referral Request except that all the data is POST'd and some fields the following addition fields have been added.

NameExample dataTypeDescription
app_echoa:1:{s:9:"PHPSESSID";s:32:"a17912534863c97a996915a384a9c6eb";}StringThe data in the request returned ot you
success1BitThis is a 1 if the user correctly authenticated and permissioned access to a box. If this is a 0, then the session_token, user_id, max_width, max_height, tag_feature awill be blank.
api_signature42991f61cf65f30ac69b5372cab57997StringThis is the API Signature of the request made. The partner may ignore this or can use this to verify that the request was actually generated by a Tagged Server and not faked.

Using the above example, the POST content might look like:

application_id=app-partner&session_token=dee0faeb184a937190d7af885b57bbfa&user_id=280&max_width=-1&max_height=box&tag_echo=&app_echo=a%3A1%3A%7Bs%3A9%3A%22PHPSESSID%22%3Bs%3A32%3A%22a17912534863c97a996915a384a9c6eb%22%3B%7D&success=1&api_sig=42991f61cf65f30ac69b5372cab57997

4.2 Photos API

This is an API for photo access.

4.2.1 tagged.photo.get

This protocol for this is an HTTP POST sent by the Partner Website to http://www.tagged.com/api.

4.2.1.1 POST request parameters
NameExample dataTypeDescription
methodtagged.photo.getStringThe name of the method call.

application_idapp-partnerStringThe identifier for the Partner’s Application as registered with Tagged.

formatjsonStringThis is an optional parameter to specify the format of the return response. Currently the only supported format is JSON.

session_tokendee0faeb184a937190d7af885b57bbfaStringAuthentication as the user. Note that this will only be live for 30 minutes after the last request.
sizemCharacterCurrently the only supported sizes are:
  • m - medium thumbnails with a max image size of 80x80 pixels
  • l - large thumbnails with a max image size of 120x120 pixels
  • 0 - full sized images with a max image size of 600x600 pixels
start0IntegerThis optional parameter is used for paginating output. It represents the starting index to use. If not provided it will be assumed to be 0.
limit20IntegerThis optional parameter is used for paginating output. If not provided it will be assumed to be 20
albumStringCurrently this field must be left blank
api_signature9e775cec6f0c9fc61ac0523ff6a82063StringThis is the API Signature of the request made.

In the above example, the Request will be:

method=tagged.photo.get&application_id=app-partner&format=json&session_token=dee0faeb184a937190d7af885b57bbfa&size=t&start=0&limit=20&album=&api_sig=9e775cec6f0c9fc61ac0523ff6a82063
4.2.1.2 Response

Tagged will return a response consisting of an array of photos with parameters

NameDescription
user_idThis along with the photo_id ensures uniqueness of the image.
photo_idThis a unique index for the photo
nameThis is the caption field of the photo
urlThis is a hyperlink to the actual image
is_profileThis is set to true if the photo is the profile photo

Here is a sample response that can generate this page.

[{"user_id":15399000,"photo_id":39050175,"name":"Through the lens","url":"http:\/\/static.tagged.com\/images\/user\/15\/39\/90\/t125-thumb-15399000-39050175.jpg","is_profile":false},{"user_id":15399000,"photo_id":39050092,"name":"Overtop Yosemite Falls","url":"http:\/\/static.tagged.com\/images\/user\/15\/39\/90\/t125-thumb-15399000-39050092.jpg","is_profile":false},{"user_id":15399000,"photo_id":39049887,"name":"Footbridge over West Waddell Creek","url":"http:\/\/static.tagged.com\/images\/user\/15\/39\/90\/t125-thumb-15399000-39049887.jpg","is_profile":false},{"user_id":15399000,"photo_id":39049941,"name":"Gibson baby","url":"http:\/\/static.tagged.com\/images\/user\/15\/39\/90\/t125-thumb-15399000-39049941.jpg","is_profile":false},{"user_id":15399000,"photo_id":39049609,"name":"Redwoods and West Berry Creek","url":"http:\/\/static.tagged.com\/images\/user\/15\/39\/90\/t125-thumb-15399000-39049609.jpg","is_profile":false},{"user_id":15399000,"photo_id":144928054,"name":"Forest","url":"http:\/\/static.tagged.com\/images\/user\/15\/39\/90\/t125-thumb-15399000-39049577.jpg","is_profile":false},{"user_id":15399000,"photo_id":33823760,"name":"Me","url":"http:\/\/i1.tagstat.com\/image05\/a\/a519\/0005054iGkp.jpg","is_profile":true}]

4.3 Friends API

This is an API for access to a user's friends list.

4.3.1 tagged.friends.get

This protocol for this is an HTTP POST sent by the Partner Website to http://www.tagged.com/api.

4.3.1.1 POST request parameters
NameExample dataTypeDescription
methodtagged.friends.getStringThe name of the method call.

application_idapp-partnerStringThe identifier for the Partner’s Application as registered with Tagged.

formatjsonStringThis is an optional parameter to specify the format of the return response. Currently the only supported format is JSON.

session_tokendee0faeb184a937190d7af885b57bbfaStringAuthentication as the user. Note that this will only be live for 30 minutes after the last request.
user_id3522838615IntegerThe user to get the friend list from. If not provided, it will assume the request user id.
api_signaturee8ecced267ca7712edceeb10a10c4e95StringThis is the API Signature of the request made.

In the above example, the Request will be:

method=tagged.friends.get&application_id=app-partner&format=json&session_token=dee0faeb184a937190d7af885b57bbfa&api_sig=e8ecced267ca7712edceeb10a10c4e95
4.3.1.2 Response

Tagged will return a response consisting of an array of friends' user ids

NameDescription
user_idThis along with the photo_id ensures uniqueness of the image.
[{"user_id":15399000},{"user_id":15399000},{"user_id":15399000},{"user_id":15399000},{"user_id":15399000},{"user_id":15399000},{"user_id":15399000}]

4.4 About Me API

This is an API for access to a user's about me info.

4.4.1 tagged.aboutme.getInfo

This protocol for this is an HTTP POST sent by the Partner Website to http://www.tagged.com/api.

4.4.1.1 POST request parameters
NameExample dataTypeDescription
methodtagged.aboutme.getInfoStringThe name of the method call.

application_idapp-partnerStringThe identifier for the Partner’s Application as registered with Tagged.

formatjsonStringThis is an optional parameter to specify the format of the return response. Currently the only supported format is JSON.

session_tokendee0faeb184a937190d7af885b57bbfaStringAuthentication as the user. Note that this will only be live for 30 minutes after the last request.
user_ids3522838615,18347282StringThis is an optional parameter to specify the users you want to get info about. You can put in one or many via a comma seperated list (no spaces). If omitted, it will default to the session authenticated user.
fieldsdisplay_name,primary_photo,birthdateString This consists a list of fields separated by comma.
  • display_name - user's display name
  • primary_photo - user's primary photo id and the url to the full size profile photo
  • mid_thumb_photo - same as above, url of the medium thumb
  • small_thumb_photo - same as above, url of the small thumb
  • gender - user's gender
  • age - user's current age
  • location - one line location
  • zip_code - only US users have zip code
  • relationship_status - user's current relationship status code
  • profile_url - user's profile url
  • birthdate - user's birth date
  • country - user's current country
  • online_status - user's current online status code
api_signature1e3c12ef74c40d01b97e15e95c98ac63StringThis is the API Signature of the request made.

In the above example, the Request will be:

method=tagged.aboutme.getInfo&application_id=app-partner&format=json&session_token=dee0faeb184a937190d7af885b57bbfa&fields=display_name%2Cprimary_photo%2Cdisplay_name&user_id=3522838615%2C18347282&api_sig=1e3c12ef74c40d01b97e15e95c98ac63
4.4.1.2 Response

Tagged will return a response consisting of some user meta info

NameDescription
user_idThis along with the photo_id ensures uniqueness of the image.
primary_photo_idThis a unique index for the photo
primary_photo_urlThis is a hyperlink to the actual image
display_nameThis is the user's display name
[{"user_id":3522838615,"primary_photo_id":60300014,"primary_photo_url":"http:\/\/static.tagged.com\/images\/user3\/35\/22\/83\/t125-thumb-3522838615-60300014.jpg","display_name":"Mark J"},{"user_id":3522838615,"primary_photo_id":60300014,"primary_photo_url":"http:\/\/static.tagged.com\/images\/user3\/35\/22\/83\/t125-thumb-3522838615-60300014.jpg","display_name":"Mark J"}]

4.5 Message API

This is an API for sending messages to users.

4.5.1 tagged.messages.send

This protocol for this is an HTTP POST sent by the Partner Website to http://www.tagged.com/api.

4.5.1.1 POST request parameters
NameExample dataTypeDescription
methodtagged.messages.sendStringThe name of the method call.

application_idapp-partnerStringThe identifier for the Partner’s Application as registered with Tagged.

formatjsonStringThis is an optional parameter to specify the format of the return response. Currently the only supported format is JSON.
session_tokendee0faeb184a937190d7af885b57bbfaStringAuthentication as the user. Note that this will only be live for 30 minutes after the last request.
to_id3522838615StringThis specifies the recipient of the message. The recipient must be a friend of the session authenticated user.
subjectA nice messageStringThe subject of your message.
messageYour message text here!StringThe body text of your message to the recipient. This string may include limited HTML tags.
api_signaturef4048556f3240fc0988536e56358daf8StringThis is the API Signature of the request made.

In the above example, the Request will be:

method=tagged.messages.getInfo&application_id=app-partner&format=json&session_token=dee0faeb184a937190d7af885b57bbfa&to_id=3522838615&subject=A+nice+message&message=Hi+this+is+a+message+from+your+friendly+%3Cstrong%3E3rd+party%3C%2Fstrong%3E+developer%21&api_sig=f4048556f3240fc0988536e56358daf8
4.5.1.2 Response

Tagged will return a response consisting of some user meta info

NameDescription
statusResponse status code of the notification send request. 200 == OK. Anything else means :(
[{"status":200}]

4.6 Test API

This is an API for simple functions.

4.6.1 tagged.test.keepalive

In some cases you may need to keep the session from expiring. You need to run an API call on the server to keep the heartbeat up. This is designed to do that.

Currently there is no response from the server

4.6.1.1 POST request parameters
NameExample dataTypeDescription
methodtagged.test.keepaliveStringThe name of the method call.

application_idapp-partnerStringThe identifier for the Partner’s Application as registered with Tagged.

formatjsonStringThis is an optional parameter to specify the format of the return response. Currently the only supported format is JSON.

session_tokendee0faeb184a937190d7af885b57bbfaStringAuthentication as the user. Note that this will only be live for 30 minutes after the last request.
api_signatureb7ef255055188a50e8258f57dbda3195StringThis is the API Signature of the request made.

In the above example, the Request will be:

method=tagged.test.keepalive&application_id=app-partner&format=json&session_token=dee0faeb184a937190d7af885b57bbfa&api_sig=b7ef255055188a50e8258f57dbda3195

5 Partner Information

This section lists information that needs to be provided to Tagged by API and Buiness Partners or information that is given to the partner by Tagged.

5.1 Global information

This is the information that needs to be provided once per Partner.

5.1.1 Partner name

The name of the partner.

5.2 Application information

This is the information this is provided on by the partner on a per application basis. Each of these is registered under an application_id which is provided by Tagged and serves as an identifier.

5.2.1 Name

This is the name of the actual Partner Component that is the Application.

Example of a Partner Application Name:

App Name

5.2.2 Description

This is a description of the object which is used on the Tagged website as sell text. This can have a maximum of 40 words and is ideally 30 words long.

Example of a Partner Application Description:

Add my app

5.2.3 Banner

Required from Business Partners only.

This is an image representing an application. The dimensions must be 250x120 pixels.

Example of a Partner Application Graphic:

5.2.4 Callback URL

This is URL on the Partner Site that the API calls that generate callbacks will call into. It is also the URL that the Tagged User is sent to Widget Referral Request. Remember in that case, there are reserved parameters that are tacked on URL.

There are a two pieces of information that are registered with Tagged that are provided to the partner in order to make API accessible and secure.

5.2.5 application_id

The unique identifier of that represents the Partner Application. This is also often called the API Key.

Example of a Partner application_id:

app-partner

5.2.6 Secret

This is a private salt that is used to sign all API calls by a Partner Application on the website. It is also used to sign all calls to the Application Callback URL.

Example of a secret (used in the examples throughout this page):

9ed8905b4e55fff3

5.3 Sample Applications

Poker and Sorority Life are some sample applications on Tagged

5.3.1 Poker

Poker is a social game from Zynga using Tagged's API. Poker is embedded within a Tagged page using an iframe.

Screenshots of Poker:

5.3.2 Sorority Life

Sorority Life has the hottest fashions and coolest cliques. Sorority Life is devoloped by Playdom. It's popular game among female users.

Screenshots of Sorority Life

Sorority Life is using Friends API to invite user's friends to play the game

A ChangeLog

This section lists major changes made from version to version.

Version: Draft 2011-04-08

  • Updated API examples
  • Added Sample Applications
  • Edited tagged.photo.get
  • Edited tagged.messages.send
  • Removed tagged.messages.sendEmail
  • Removed tagged.aboutme.getBirthday

Version: Draft 2008-05-15

  • Implemented partner-initiated API access
  • Documented tagged.friends.getTeamDetails
  • Documented tagged.messages.send
  • Documented tagged.messages.sendEmail

Version: Draft 2007-08-30

  • Added tagged.friends.get
  • Added tagged.aboutme.*

Version: Draft 2006-03-21

  • Added tagged.test.keepalive method
  • Added spec on widget content
  • Updated widget widths temporarily for the first release

Version: Draft 2006-03-12

  • Created Widget Authorization Request
  • Widget: middle image dimension was incorrect

Version: Draft 2006-03-06

  • Created photo.* API.
  • "boxx" is now "box"

Version: Draft 2006-03-02

  • First Draft