GROU.PS API Documentation

Version: 3

Status: Current, Production

Audience: Developers

Index1. Getting Started2. How to use the API3. How to pass the API key and api_secret

How to create the api_secret4. Response Format

XML Counterparts of JSON representationsSuccessful ResponsesFailure Responses

5. Reference6. Examples

1. Getting StartedWelcome to the GROU.PS API.

GROU.PS API allows you to programmatically access your group's content and manipulate it.

In order to use the GROU.PS API, you'll need a:

Application Keyand Application Secret.

Only the group founders/admins can grant you these.

2. How to use the APIThe GROU.PS API works through the standard REST protocol.

The authentication is based on an oAuth 1.0 like mechanism.

All requests should go to:

https://grou.ps/api/v3/{groupname}/{module}/{function}

Note: The use of SSL is highly recommended.

3. How to pass the API key and api_secretSend the API key in plain format using GET with the following parameter: api_keySend the API api_secret in an encrypted format using GET using the following parameter:api_secret

3.1 How to create the api_secret?

1. First and foremost the requester's time should be properly set and kept up to date usingntp.

2. SHA1 sign {group name}|{module}|{function}|{date as Y-m-d (year-month-day)} in binaryform with the secret API key e.g. in php: hash_hmac('sha1',$group_name.'|'.$module.'|'.$function.'|'.date('Y-m-d'), $secret,true)

3. Base64 encode the output of the second step.4. Send the result with GET as api_secret

4. Response FormatThe GROU.PS API uses JSON as the standard response format.

JSON, or JavaScript Object Notation, is a simple machine-readable data-interchange format,which makes constructing API applications in JavaScript easy (though it can be used from otherlanguages too!). For more information about JSON, visit json.org.

To return an API response in JSON format, send a parameter "format" in the request with avalue of "json".

4.1 XML Counterparts of JSON representationsExample 1

{foo:{bar:"baz"}}

Example 2

{foo:{bar:"baz", woo: { yay: "hoopla" }}}

Example 3

{foo: {"_content": "text here!"}}

text here!

Example 4

For repeated elements (such as the element when fetching a list of photos), an array is used asthe object member value (the member key represents the element name). Each value in thearray is then an object representing a child element.

{outer: {photo: [{id: "1"},{id: "2"}]}}

4.2 Successful ResponsesWhen a request is successful, the following JSON is returned:

groupsApi({}); The single object passed in the function call represents the REST outerelement. The root element of the REST response is then a member of this object (the stat paramalso is - check this to see if the call was successful). For instance, flickr.blogs.getList has adocumented response as follows:

groupsApi({ "stat": "ok", "blogs": { "blog": [ { "id" : "73", "name" :"Bloxus test", "needspassword" : "0", "url" : "http://remote.bloxus.com/" },{ "id" : "74", "name" : "Manila Test", "needspassword" : "1", "url" :"http://userland.com/" } ] } })

In JavaScript, displaying a list of a user's blogs is then straight forward:

function groupsApi(rsp){ if (rsp.stat != "ok"){ // something broke! return; }for (var i=0; i

5.1 actions

5.1.1 actions.getGroupActions

Parameters:

offset (optional):limit (optional):

Returns:

action_idaction_typeaction_moduleaction_timeaction_like_countaction_comment_countaction_html_templateaction_html_paramsaction_subject

membership_idmember_idmember_namemember_usernamemember_avatar

5.1.2 actions.getMemberActions

Parameters:

userIdoffset (optional):limit (optional):

Returns:

action_idaction_typeaction_moduleaction_timeaction_like_countaction_comment_countaction_html_templateaction_html_params

action_groupgroup_idgroup_urlgroup_titlegroup_logo

action_subjectmembership_idmember_idmember_namemember_usernamemember_avatar

5.1.3 actions.deleteAction

Parameters:

object

Returns: N/A

5.1.4 actions.getComments

Parameters:

object

Returns:

commentIduserProfileLinkuserProfileNameuserNameuserIdaddTimedeletablecommentuserAvatar

5.1.5 actions.addComment

Parameters:

objectcommentuser_id

Returns:

comment_iduser_profile_inkuser_full_nameuser_usernameuser_idtimeuser_avatarcomment

5.1.6 actions.deleteComment

Parameters:

comment_id

Returns: N/A

5.1.7 actions.getNewsfeed

Parameters:

offset (optional):limit (optional):member_id (optional):action_id (optional):format (optional): jsonp

Returns:

statuscontent

idtypewhenauthor

idusernamenameavatar

likesidname

commentsidauthor

idnameavatar

msgwhen

mediaidthumbnailvideo

msglimitoffsetnext

5.2 admin

5.2.1 banUser

Parameters:

member_id

Returns: N/A

5.3 authentication

5.3.1 authentication.signup

Parameters:

emailpassword

Returns:

usernameprofile_url

5.3.2 authentication.logout

Parameters:

No need parameter.

Returns:

status

5.3.3 authentication.resetPassword

Parameters:

email

Returns:

status

5.3.3 authentication.login

Parameters:

email

password

remember (true or false)

groupName

Returns:

status

content

id

username

name

avatar

points

email

gender

subscribedGroups

groupName

groupCName

id

name

latitude

longitude

5.4 blogs

5.4.1 addBlogPost

Parameters:

member_idtitlepost

Returns:

post_url

5.4.2 getPosts

Parameters:

limit (optional)offset (optional)

Returns:

posts[]idtitlebodydatelinkuser

idusername

5.4.3 getPost

Parameters:

post_id

Returns:

idtitlebodydatelinkuser

idusername

5.4.4 deletePost

Parameters:

post_id

Returns: N/A

5.5 calendar

5.5.1 calendar.getEvents

Parameters:

year (optional)

Returns:

events[]idtitledescstarts

daymonth

endsmonthday

5.5.2 calendar.getEvent

Parameters:

event_id

Returns:

event_iduser_iddescriptionstatusadd_timestartsendsaddresstitleshow_maprepeat_categoryticket_pricemax_attendants

5.6 files

5.6.1 getFiles

Parameters: N/A

Returns:

files[]file_idtitlesizenamedateusericoncommentstagsreadable_sizehashurldownload_urltimestampuser_icondownload_count

5.6.2 getFile

Parameters:

file_hash

Returns:

file_idtitlesizenamedateusericoncommentstagsreadable_sizeurldownload_urltimestampuser_icondownload_count

5.7 generals

5.7.1 generals.getMembersCount

Parameters: N/A

Returns: []

5.7.2 generals.getTagline

Parameters: N/A

Returns: []

5.7.3 generals.getDescription

Parameters: N/A

Returns: []

5.7.4 generals.getTitle

Parameters: N/A

Returns: []

5.7.5 generals.getMembers

Parameters: N/A

Returns: []

5.8 subgroups

5.8.1 group.getSubgroups

Parameters: N/A

Returns:

subgroups[]subgroup_id

5.8.2 group.getSubgroup

Parameters:

subgroup_id

Returns: N/A

5.8.3 group.deleteSubgroupMember

Parameters:

subgroup_idmember_id

Returns: N/A

5.9 imsg (internal messages)

5.9.1 imsg.sendMessage

Parameters:

to: as user_idfrom: as user_idmsg

Returns: N/A

5.9.2 imsg.getConversationWith

Parameters:

Need an authorized account. (valid_user)

userName (not member_id)

page (optional)

Returns:

statuscontent

msg_idmsgdateupdate_datefromtois_read_by_from

is_read_by_to

5.9.3 imsg.getInbox

Parameters:

No need parameters.

Returns:

idis_read

msg

from

id

avatar

name

when

5.9.4 imsg.getGroupedInbox

Parameters:

No need parameters.

Returns:

status

content

id

unreaded_count

msg

user

id

username

avatar

name

when

5.10 members

5.10.1 members.getFullName

Parameters

username: not user_id

Returns: [...]

5.10.2 members.setFullName

Parameters

username: not user_idfullname

Returns: N/A

5.10.3 members.getBirthday

Parameters

username: not user_id

Returns: []

5.10.4 members.setBirthday

Parameters

username: not user_idnew_birthday

Returns: N/A

5.10.5 members.getPhoto

Parameters

username: not user_id

Returns: []

5.10.6 members.setPhoto

Parameters

username: not user_iddata: base64 format

Returns: N/A

5.10.7 members.getNationality

Parameters

username: not user_id

Returns:

nationality: 2-letter country code http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

5.10.8 members.setNationality

Parameters

username: not user_idnew_nationality: 2-letter country code http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

Returns: N/A

5.10.9 members.getSex

Parameters

username: not user_id

Returns:

result: male or female

5.10.10 members.setSex

Parameters

username: not user_idnew_sex: male or female

Returns: N/A

5.10.11 members.getFriends

Parameters

username: not user_id

Returns:

friends[]membership_idmember_namemember_usernamemember_avatar

5.10.12 members.getMemberInfo

Parameters:

username: not user_id

Returns:

member

nameactivity_pointsavataris_onlineusernameidprofilelast_status

5.10.13 members.getProfile

Parameters:

username: not user_id

Returns:

statuscontent

id

username

name

avatar

points

email

gender

activities

[]friends

member_id

fullName

avatar

username

sex

birthday

5.10.14 members.getOnlineMembers

Parameters:

No need parameters.

Returns:

status

content

id

username

name

avatar

points

email

gender

5.11 videos

5.11.1 getVideos

Parameters:

offset

per_page

member_id

Returns:

videos[]idtitlelinkthumbdateuser id username

5.11.2 getVideo

Parameters:

video_id

Returns:

videos[]idtitlelinkthumbdateuser id username

5.11.3 shareVideo

Parameters:

member_id

url

title

tags

Returns: N/A

5.11.4 deletevideo

Parameters:

video_id

Returns: N/A

5.12 talks

5.12.1 getcategories

Parameters: N/A

Returns:

BO ARRAY.

5.12.2 getMessages

Parameters: N/A

Returns:

BO

5.12.3 getmessage

Parameters:

messageId

Returns:

HTML

5.12.4 postnewmessage

Parameters:

subjectmessage

member_login

Optional: * cat_id

Returns:

videos[]idtitlelinkthumbdateuser id username

5.12.5 replymessage

Parameters:

messageIdmessage

Returns:

messageId

5.13 photos

5.13.1 getPhotos

Parameters: N/A

Returns:

idtitledescriptionlinkdatealbum[]

id

name

description

user[]

id

username

5.13 photos

5.13.1 deletephoto

Parameters:

photo_id

Returns:

patlad.

PHP Fatal error: Call to a member function getPhotoUrl() on a non-object in/www/grou.ps/releases/20121221174333/includes/api/photos.php on line 696

5.14 wiki

5.14.1 search

Parameters:

q

Returns:

count

data[]

title

id