Status Code	Description
004	Call is not define in the api.
001	An unknown error occurred. Please try again.
0	Failed.
1	Success.
2	The service is currently not available. Please try again later.
3	Invalid API key.
4	Invalid signature.
5	Invalid version number.
6	Invalid call id.
900	The application has exceeded the maximum number of requests allowed. Please try again later.
101	One of the parameters specified is invalid.
404	One of the required parameters is missing.
500	An user must be logged in to perform this request.
501	The currently logged in user does not have appropriate permissions to perform this request.

Access Private Data Securely!

Basic Auth!

Basic Authentication sends user credentials in the header of the HTTP request. This makes it easy to use, but insecure and difficult to track.

Keeping the session alive!: when you login first time using basic auth, you will get session id (sid) in response code, you can use that session id in url to continue the user session on other pages without needing to send username and password again.

Note: if you need to continue session from a different server, then you must pass session id with ip of a old server which session was created from, else it won’t authenticate and log you out. Ex: http://path_to_the _page.com/status/sid=session_id&ip=old_server_ip_if_server_changed.

oAuth!

oAuth is required for accessing private data of a user and user must give permission to application for accessing there private data.

Requesting Token: http:://iresala.com/oauth/request_token

Authorizing from user: http://iresala.com/oauth/authorize

Accessing Token: http://iresala.com/oauth/access_token

oAuth Tools and articles:

· http://oauth.net/

· http://oauth.net/code

· http://oauth.net/core/1.0/

· http://en.wikipedia.org/wiki/OAuth

· http://term.ie/oauth/example/client.php

User Management & Accessing user info

User

Managing User and accessing his data, of course with his permission.

User Avatar’s

We have 5 different sizes profile avatars for all the users. Which are following:

1. Custom 300x225 (large size) for site use mostly.

2. 128x128

3. 64x64

4. 48x48

5. 32x32

These sizes changes based on dimension of the image. The above sizes are max sizes for each dimension, which means if they are vertically bigger, then there real size will be different, so the images stay in their original look and don’t look stretched apart.

You can retrieve the profile avatars with following links:

1. http://username.iresala.com/avatar/custom.jpg

2. http://username.iresala.com/avatar/128.jpg

3. http://username.iresala.com/avatar/64.jpg

4. http://username.iresala.com/avatar/48.jpg

5. http://username.iresala.com/avatar/32.jpg

Links are self explanatory. If there is no user profile avatar, then it will retrieve the default avatar and show that.

Status Updates (what are you doing today!)

Status updates (News Feed)

Managing news feed.

Everyone Feed List – [GET] http://iresala.com/status.xml
every user status updates

Parameters

Name	Description	Required	Default
after	Pagination use for skipping rows and start displaying after it.	No	0
show	Pagination use for limiting to pull the certain amount of rows	No	20

Search Feed list – [GET] http://iresala.com/status/{type}/{search_word}.xml
Accessing list of comments of the media.

Parameters

Name	Description	Required	Default
Search_word	Search word to search for	Yes	Null
type	Filter by type (image, video, feed, media (images, videos) or null for all)	No	Null
after	Pagination use for skipping rows and start displaying after it.	No	0
show	Pagination use for limiting to pull the certain amount of rows	No	20

User Feed List – [GET] http://username.iresala.com/status/{type}.xml
Accessing list of feeds for user and his fiend/following people feeds which can be filter by parameters.

Parameters

Name	Description	Required	Default
username	username of the feed owner	Yes
type	Filter by type (image, video, feed, media (images, videos) or null for all)	No	Null
after	Pagination use for skipping rows and start displaying after it.	No	0
show	Pagination use for limiting to pull the certain amount of rows	No	20

User Self Feed List – [GET] http://username.iresala.com/status/ifeed/{type}.xml
Accessing list of feeds for user only and not his friends or anyone else.

Parameters

Name	Description	Required	Default
username	username of the feed owner	Yes
type	Filter by type (image, video, feed, media (images, videos) or null for all)	No	Null
after	Pagination use for skipping rows and start displaying after it.	No	0
show	Pagination use for limiting to pull the certain amount of rows	No	20

User Mentions Feed List – [GET] http://username.iresala.com/status/mentions.xml
Accessing list of feeds where user have been mentioned at.

Parameters

Name	Description	Required	Default
username	username of the feed owner	Yes
after	Pagination use for skipping rows and start displaying after it.	No	0
show	Pagination use for limiting to pull the certain amount of rows	No	20

Thread Feed List – [GET] http://username.iresala.com/status/thread/{thread_id}.xml
feed discussion list for a thread with their replies.

Parameters

Name	Description	Required	Default
username	username of the feed owner	Yes
thread_id	Thread id to pull the conversation of	Yes	Null
after	Pagination use for skipping rows and start displaying after it.	No	0
show	Pagination use for limiting to pull the certain amount of rows	No	20

Feed Create – [POST] http://username.iresala.com/status.xml
create a feed

Parameters

Name	Description	Required	Default
username	username of the feed owner	Yes
type	Type of feed (feed, image, video or audio)	Yes	feed
text	User feed (can be empty if thumbnail is set)	Yes
reply_to	Replying to feed, add feed id of the replying feed	No	0
media_id	Media id for which is being talk about	No
thumbnail	Thumbnail link for the image/video/audio	No
direct_link	1 link with feed, with or without thumbnail	No

Feed Modify – [PUT] http://username.iresala.com/status/{feed_id}.xml
Modifying user feed, only user himself can do.

Parameters

Name	Description	Required	Default
username	username of the feed owner	Yes
feed_id	Feed id to make modification to	Yes
type	Type of feed (feed, image, video or audio)	No	feed
text	User feed (can be empty if thumbnail is set)	No
reply_to	Replying to feed, add feed id of the replying feed	No	0
media_id	Media id for which is being talk about	No
thumbnail	Thumbnail link for the image/video/audio	No
direct_link	1 link with feed, with or without thumbnail	No

Feed Delete – [DELETE] http://username.iresala.com/status/{feed_id}.xml
Deleting feed

Parameters

Name	Description	Required	Default
username	username of the user	Yes
feed_id	Feed id to make modification to	Yes

Feed Vote – [POST] http://username.iresala.com/status/{feed_id}.xml
Adding user vote on the feed, thumbs up or thumbs down for a feed.

Parameters

Name	Description	Required	Default
username	username of the feed owner	Yes
feed_id	feed id which needs to be modified	Yes
vote	“up” or “down” vote on the comment	Yes	down

Feed Report Spam – [PUT] http://username.iresala.com/status/{feed_id}.xml
Reporting Spam

Parameters

Name	Description	Required	Default
username	username of the feed owner	Yes
feed_id	Feed id to make modification to	Yes
spam	What is problem with this feed. user massage	Yes (can be null)

Organize Albums

Albums

To organize media, use albums. Also accessing the albums or its media, it will check user permission first, if he is allowed or given permission to access the album or its media.

Album View – [GET] http://username.iresala.com/album/{album_id}/only.xml
Pass album id and it will return all the sub album of the album. If you don’t pass any album id, it will show top parent albums

Parameters

Name	Description	Required	Default
username	username of the album owner	Yes
parent_id	Album id to get the sub albums of this album	No	NULL
after	Pagination use for skipping rows and start displaying after it.	No	0
show	Pagination use for limiting to pull the certain amount of rows	No	20

Album Create – [POST] http://username.iresala.com/album/only.xml
it will create album in the parent given album.

Parameters

Name	Description	Required	Default
username	username of the album owner	Yes
name	Name of the album	Yes
parent_id	Parent album id to put this album in the parent album	No
private	‘yes’ (if its private) or ‘no’ (if it’s not private)	No	no

Album Modify – [PUT] http://username.iresala.com/album/{album_id}/only.xml
Modifies the album name and move the album to new location, if parent album was provided too.

Parameters

Name	Description	Required	Default
username	username of the album owner	Yes
album_id	Album id to make modification to	Yes
name	Name of the album	No
parent_id	Parent album id to put this album in the parent album	No
private	‘yes’ (if its private) or ‘no’ (if it’s not private)	No	no

Album Delete – [DELETE] http://username.iresala.com/album/{album_id}/only.xml
Delete the album.

Parameters

Name	Description	Required	Default
username	username of the album owner	Yes
album_id	Album id to delete	Yes

Album Permission View – [GET] http://username.iresala.com/album/{album_id}/permission.xml
To see which user has permission to view this album.

Parameters

Name	Description	Required	Default
username	username of the album owner	Yes
album_id	Album id to get the permission list of	Yes

Album Permission Give – [POST] http://username.iresala.com/album/{album_id}/permission.xml
Give permission to this album to another user.

Parameters

Name	Description	Required	Default
username	username of the album owner	Yes
album_id	Album id to give permission to	Yes
user	username to give access to (ignore this, if you putting email)	No
~~email~~	~~Email address to give access to~~	No
~~full_name~~	~~Full name of the user, if you going to use email address~~	No

Album Permission Take – [DELETE] http://username.iresala.com/album/{album_id}/permission.xml
Remove permission for a user.

Parameters

Name	Description	Required	Default
username	username of the album owner	Yes
album_id	Album id to take permission from	Yes
user	username to remove access of (ignore this, if you putting email)	No
~~email~~	~~Email address to remove access of~~	No

Accessing & Managing Media

Media

Accessing users media and managing them.

Searching Media – [GET] http://iresala.com/tag/{media_type}/{sub_type}/{search_word}.xml
search the media rows from all the users and returns the list of rows. This method can also be used for finding related media and also you can pass multiple tags and it will pull related media according to the tags.

Parameters

Name	Description	Required	Default
media_type	image, video, layout or empty for all	No	NULL
sub_type	Sub type it’s for more categorizing, not in use for now	No	NULL
search_word	Any given search words, which user needs or can be used for related media. You can also pass preset values, which are self explanatory. Preset Values: · Populare (populare media) · Commented (most commented media) · Viewed (most viewed media) · Scored (highest scored media) · Voted (best voted media)	Yes	NULL
after	Pagination use for skipping rows and start displaying after it.	No	0
show	Pagination use for limiting to pull the certain amount of rows	No	20
XML Response:

<status_valid>1</status_valid>

<status_code>1</status_code>

<status_description>Success.</status_description>

</paging>

<items>

<item>

<media_id>Be8YN19w3Ak</media_id>

<album_id>0</album_id>

<media_type>image</media_type>

<media_sub_type></media_sub_type>

<server_name></server_name>

<embedded_code></embedded_code>

<file_url></file_url>

<file_name>2-4.jpg</file_name>

<file_extension>jpg</file_extension>

<file_size>88829</file_size>

<file_type>image/jpeg</file_type>

<word_tags>work_to_search</word_tags>

<taken_latitude></taken_latitude>

<taken_longitude></taken_longitude>

<total_views>0</total_views>

<total_scores>0</total_scores>

<total_contest_position>0</total_contest_position>

<total_voting>0</total_voting>

<total_rating>0</total_rating>

<total_people_rated>0</total_people_rated>

<total_comments>0</total_comments>

<created_date>2009-05-13 12:52:56</created_date>

<username>basit</username>

</item>

// more item rows if any more… -- remove this line

</items>

</response>

User Media by Album – [GET] http://username.iresala.com/album/{album_id}.xml
Accessing user media by album wise, we will also be using same url scheme for managing the media.

Parameters

Name	Description	Required	Default
username	username of the media owner	Yes
album_id	Album id for getting media of that album	No	0
after	Pagination use for skipping rows and start displaying after it.	No	0
show	Pagination use for limiting to pull the certain amount of rows	No	20

Media Next or Previous Album Rows – [GET] http://username.iresala.com/album/{album_id}/{position}/{media_id}/{media_type}.xml
Accessing user media by album wise, we will also be using same url scheme for managing the media.

Parameters

Name	Description	Required	Default
username	username of the media owner	Yes
album_id	Album id for getting media of that album	Yes
position	‘next’ or ‘prev’. to get after current media rows, then use next or to get previous rows from current rows, then use prev	Yes
media_id	Current media id to get rows after this or before this	Yes
media_type	To filter the media by there types (image or video), if provided null, then both types will fetch	No	Null
after	Pagination use for skipping rows and start displaying after it.	No	0
show	Pagination use for limiting to pull the certain amount of rows	No	20

Media Create – [POST] http://username.iresala.com/album/{album_id}.xml
it will create image, video or layout media in the given album.

Parameters

Name	Description	Required	Default
username	username of the media owner	Yes
album_id	Album id for adding media in the album	No	0
type	Media type image or video.	No	image
add_file	This field can be url or base64 encoded media file. (required for image only)	Yes/No
embedded_code	Video embedded code (required for video only, until video upload feature comes). Media type changes to video automatically for this	Yes/No	Null
thumbnail	Can be direct upload, url or base64 encoded image. (useful only for video)	No	Null
length	Video length	No	Null
title	Title of the media	No	Null
description	Description of the media	No	Null
add_word_tags	Multiple tags separated by space	No	Null
taken_latitude	Latitude where the media was created from.	No	Null
taken_longitude	Longitude where the media was created from.	No	Null
width	New width of the image you are uploading, if you want to resize it after upload.	No	Null
height	New height of the image you are uploading, if you want to resize it after upload.	No	Null
file_name	For renaming the file name on upload, it will add increment, if file already exist in the album	No	Null

Media Modify – [PUT] http://username.iresala.com/album/{album_id}.xml
Modifies the media info and move the file/media to new location, if album was set different was.

Parameters

Name	Description	Required	Default
username	username of the media owner	Yes
media_id	Media id to which the user making modification to	Yes
album_id	Album id for adding media in the album	No	0
embedded_code	Video embedded code (required for video only, until video upload feature comes). Media type changes to video automatically for this	Yes/No	Null
thumbnail	Can be direct upload, url or base64 encoded image. (useful only for video)	No	Null
length	Video length	No	Null
title	Title of the media	No	Null
description	Description of the media	No	Null
add_word_tags	Multiple tags separated by space	No	Null
remove_word_tags	Multiple tags separated by space	No	Null
taken_latitude	Latitude where the media was created from.	No	Null
taken_longitude	Longitude where the media was created from.	No	Null
file_name	For renaming the file names, currently supported for images only	No	Null

Media Delete – [DELETE] http://username.iresala.com/{media_id}.xml
Delete the media.

Parameters

Name	Description	Required	Default
username	username of the media owner	Yes
media_id	Media id to delete	Yes

Vote on media – [POST] http://username.iresala.com/vote/{media_id}.xml
User vote on media.

Parameters

Name	Description	Required	Default
username	username of the media owner	Yes
media_id	Media id for which is being voted on	Yes
Vote	Vote of user “up” or “down” (thumbs up and down)	Yes

Media Links and Images

To Access media information or to get media images, then following are the links:

o http://username.iresala.com/media_id_here (media detail page)

o http://username.iresala.com/media_id_here.extension (media large image)

o http://username.iresala.com/thumbnail/media_id_here.jpg (media thumbnail image)

o http://username.iresala.com/media_id_here.json (to get media information in json format)

o http://username.iresala.com/media_id_here.xml (to get media information in xml format)

These links are self explanatory but make sure username is the user who created the media, else result might not show what you desire of.

Comment

Managing media comments.

Comments List – [GET] http://username.iresala.com/comment/{media_id}.xml
Accessing list of comments of the media.

Parameters

Name	Description	Required	Default
username	username of the media owner	Yes
media_id	Media id for getting comment of that media	Yes
after	Pagination use for skipping rows and start displaying after it.	No	0
show	Pagination use for limiting to pull the certain amount of rows	No	20

Comment Create – [POST] http://username.iresala.com/comment/{media_id}.xml
Add user comment on the media.

Parameters

Name	Description	Required	Default
username	username of the media owner	Yes
media_id	Media id for which is being voted on	Yes
text	User comments.	Yes
reply_to	Replying to comment, add comment id of the replying comment	No	0

Comment Modify – [PUT] http://username.iresala.com/comment/{media_id}.xml
Modifying user comment, only user himself can do.

Parameters

Name	Description	Required	Default
username	username of the media owner	Yes
media_id	Media id for which is being voted on	Yes
comment_id	Comment id which needs to be modified	Yes
text	User comments.	Yes

Comment Vote – [POST] http://username.iresala.com/comment/{media_id}.xml
Adding user vote on the comment, thumbs up or thumbs down for a comment.

Parameters

Name	Description	Required	Default
username	username of the media owner	Yes
media_id	Media id for which is being voted on	Yes
comment_id	Comment id which needs to be modified	Yes
Vote	“up” or “down” vote on the comment	Yes	down

Followers / Friends / Following

Get to know who likes who with complete access to all users fan and friends.

Friends – [GET] http://username.iresala.com/people/friends.xml
List of friends of the user.

Parameters

Name	Description	Required	Default
username	username of the user	Yes
after	Pagination use for skipping rows and start displaying after it.	No	0
show	Pagination use for limiting to pull the certain amount of rows	No	20

Mutual Friends – [GET] http://username.iresala.com/people/mutual/username_with.xml
List of friends of the user.

Parameters

Name	Description	Required	Default
username	username of the user	Yes
username_with	username with to match and find mutual friends with	No	Logged in user
after	Pagination use for skipping rows and start displaying after it.	No	0
show	Pagination use for limiting to pull the certain amount of rows	No	20

Followers – [GET] http://username.iresala.com/people/followers.xml
List of followers of the user.

Parameters

Name	Description	Required	Default
username	username of the user	Yes
after	Pagination use for skipping rows and start displaying after it.	No	0
show	Pagination use for limiting to pull the certain amount of rows	No	20

Following – [GET] http://username.iresala.com/people/following.xml
List of users which profile owner following to.

Parameters

Name	Description	Required	Default
username	username of the user	Yes
after	Pagination use for skipping rows and start displaying after it.	No	0
show	Pagination use for limiting to pull the certain amount of rows	No	20

Suggestion – [GET] http://username.iresala.com/people/suggest.xml
List of suggestion to the user for following them

Parameters

Name	Description	Required	Default
username	username of the user	Yes
after	Pagination use for skipping rows and start displaying after it.	No	0
show	Pagination use for limiting to pull the certain amount of rows	No	20

Start Following – [POST] http://username.iresala.com/follow.xml
Start following this user

Parameters

Name	Description	Required	Default
username	username of the user	Yes

Stop Following – [DELETE] http://username.iresala.com/follow.xml
Stop following this user

Parameters

Name

Description

Required

Default

username

username of the user

Yes

Block Follower – [PUT] http://username.iresala.com/follow.xml
Block this follower.

Parameters

Name	Description	Required	Default
username	username of the user	Yes
Block	‘Yes’ to block or “No” to unblock	Yes	No

Unblock Follower – [PUT] http://username.iresala.com/follow.xml
Unblock this follower.

Parameters

Name	Description	Required	Default
username	username of the user	Yes
Block	‘Yes’ to block or “No” to unblock	Yes	No