You are on page 1of 23

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 api_secret
How to create the api_secret
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:
Application Key
and Application Secret.
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 api_secret


Send the API key in plain format using GET with the following parameter: api_key
Send 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 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_secret

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 dierent 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:
oset (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
oset (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.1.7 actions.getNewsfeed
Parameters:
oset (optional):
limit (optional):
member_id (optional):
action_id (optional):
format (optional): jsonp
Returns:
status
content
id
type
when
author
id
username
name
avatar
likes
id
name

comments
id
author
id
name
avatar
msg
when
media
id
thumbnail
video
msg
limit
oset
next

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

5.3 authentication
5.3.1 authentication.signup
Parameters:
email
password
Returns:
username
profile_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_id
title
post
Returns:
post_url
5.4.2 getPosts
Parameters:
limit (optional)
oset (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 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_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.9.2 imsg.getConversationWith
Parameters:
Need an authorized account. (valid_user)
userName (not member_id)
page (optional)
Returns:
status
content
msg_id
msg
date
update_date
from
to
is_read_by_from
is_read_by_to
5.9.3 imsg.getInbox
Parameters:
No need parameters.
Returns:
id
is_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_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.10.13 members.getProfile
Parameters:
username: not user_id
Returns:
status
content
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:
oset
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:
BO ARRAY.

5.12.2 getMessages
Parameters: N/A
Returns:
BO
5.12.3 getmessage
Parameters:
messageId
Returns:
HTML
5.12.4 postnewmessage
Parameters:
subject
message
member_login
Optional: * cat_id
Returns:
videos[]
id
title
link
thumb
date
user id username
5.12.5 replymessage
Parameters:
messageId
message
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:
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