GROU.

PS API Documentation
Version: 3 Status: Current, Production Audience: Developers

Index
1. Getting Started 2. How to use the API 3. How to pass the API key and signature How to create the api_signature 4. Response Format XML Counterparts of JSON representations Successful Responses Failure Responses 5. Reference 6. Examples

1. Getting Started
Welcome 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: developer key and secret code. Only the group founders/admins can grant you these.

2. How to use the API

The 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 signature

Send the API key in plain format using GET with the following parameter: api_key Send the API signature in an encrypted format using GET using the following parameter: api_signature

3.1 How to create the api_signature?

1. First and foremost the requester's time should be properly set and kept up to date using ntp. 2. SHA1 sign {group name}|{module}|{function}|{date as Y-m-d (year-month-day)} in binary form 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_signature

4. Response Format
The 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 other languages 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 a value of "json".

4.1 XML Counterparts of JSON representations

Example 1
{foo:{bar:"baz"}} <foo bar="baz" />

Example 2
{foo:{bar:"baz", woo: { yay: "hoopla" }}} <foo bar="baz"><woo yay="hoopla" /></foo>

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

<foo>text here!</foo>

Example 4 For repeated elements (such as the element when fetching a list of photos), an array is used as the object member value (the member key represents the element name). Each value in the array is then an object representing a child element.
{outer: {photo: [{id: "1"},{id: "2"}]}} <outer><photo id="1" /> <photo id="2" /></outer>

4.2 Successful Responses

When a request is successful, the following JSON is returned: groupsApi({}); The single object passed in the function call represents the REST outer element. The root element of the REST response is then a member of this object (the stat param also is - check this to see if the call was successful). For instance, flickr.blogs.getList has a documented 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<rsp.blogs.blog.length; i++){ var blog = rsp.blogs.blog[i]; var div = document.createElement('div'); var txt = document.createTextNode(blog.name); div.appendChild(txt); document.body.appendChild(div); } }

4.3 Failure Responses

Failure responses also call the groupsApi() method, but with a different JSON object. The object is not structured like the REST failure responses - instead it's simplified for JSON. For example:
groupsApi({ "stat" : "fail", "message" : "Missing signature" })

From JavaScript, you can check rsp.stat for failure, and then read the error from rsp.message.

5. Reference
We won't go into too much of detail in this documentation. The nomenclature should be mostly self-explanatory. But feel free to ask in the forum if you have any questions.

5.1 actions
5.1.1 actions.getGroupActions Parameters: offset (optional): limit (optional): Returns: action_id action_type action_module action_time action_like_count action_comment_count action_html_template action_html_params action_subject membership_id member_id member_name member_username member_avatar 5.1.2 actions.getMemberActions Parameters: userId offset (optional): limit (optional): Returns: action_id action_type action_module action_time action_like_count action_comment_count action_html_template action_html_params

action_group group_id group_url group_title group_logo action_subject membership_id member_id member_name member_username member_avatar 5.1.3 actions.deleteAction Parameters: object Returns: N/A 5.1.4 actions.getComments Parameters: object Returns: commentId userProfileLink userProfileName userName userId addTime deletable comment userAvatar 5.1.5 actions.addComment Parameters: object comment user_id

Returns: comment_id user_profile_ink user_full_name user_username user_id time user_avatar comment 5.1.6 actions.deleteComment Parameters: comment_id Returns: N/A

5.2 admin
5.2.1 banUser Parameters: member_id Returns: N/A

5.3 authentication
5.3.1 signup Parameters: email password Returns: username profile_url

5.4 blogs

5.4.1 addBlogPost Parameters: member_id title post Returns: post_url 5.4.2 getPosts Parameters: limit (optional) offset (optional) Returns: posts[] id title body date link user id username 5.4.3 getPost Parameters: post_id Returns: id title body date link user

id username 5.4.4 deletePost Parameters: post_id Returns: N/A

5.5 calendar
5.5.1 calendar.getEvents Parameters: year (optional) Returns: events[] id title desc starts day month ends month day 5.5.2 calendar.getEvent Parameters: event_id Returns: event_id user_id description status add_time

starts ends address title show_map repeat_category ticket_price max_attendants

5.6 files
5.6.1 getFiles Parameters: N/A Returns: files[] file_id title size name date user icon comments tags readable_size hash url download_url timestamp user_icon download_count 5.6.2 getFile Parameters: file_hash Returns: file_id

title size name date user icon comments tags readable_size url download_url timestamp user_icon download_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 subgroups.getSubgroups Parameters: N/A Returns: subgroups[] subgroup_id 5.8.2 subgroups.getSubgroup Parameters: subgroup_id Returns: N/A 5.8.3 subgroups.deleteSubgroupMember Parameters: subgroup_id member_id Returns: N/A

5.9 imsg (internal messages)

5.9.1 imsg.sendMessage Parameters: to: as user_id from: as user_id msg Returns: N/A

5.10 members
5.10.1 members.getFullName Parameters username: not user_id

Returns: [...] 5.10.2 members.setFullName Parameters username: not user_id fullname Returns: N/A 5.10.3 members.getBirthday Parameters username: not user_id Returns: [] 5.10.4 members.setBirthday Parameters username: not user_id new_birthday Returns: N/A 5.10.5 members.getPhoto Parameters username: not user_id Returns: [] 5.10.6 members.setPhoto Parameters username: not user_id data: 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_id new_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_id new_sex: male or female Returns: N/A 5.10.11 members.getFriends Parameters username: not user_id Returns: friends[] membership_id member_name

member_username member_avatar 5.10.12 members.getMemberInfo Parameters: username: not user_id Returns: member name activity_points avatar is_online username id profile last_status

5.11 videos
5.11.1 getVideos Parameters: offset per_page member_id Returns: videos[] id title link thumb date user id username 5.11.2 getVideo Parameters:

video_id Returns: videos[] id title link thumb date user 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: 5.12.2 getMessages Parameters: N/A Returns:

5.12.3 getmessage Parameters: messageId Returns: 5.12.4 postnewmessage Parameters: subject message cat_id Returns: 5.12.5 replymessage Parameters: messageId per_page Returns: messageId

5.13 photos
5.13.1 getPhotos Parameters: N/A Returns: id title description link date album[] id name

description user[] id username

5.13 photos
5.13.1 deletephoto Parameters: photo_id Returns:

5.14 wiki
5.14.1 search Parameters: q Returns: count data[] title id