Upload
emre-sokullu
View
29
Download
3
Embed Size (px)
DESCRIPTION
GROU.PS API Doc now with more functions.
Citation preview
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:
Returns:
status
5.3.3 authentication.login
Parameters:
password
remember (true or false)
groupName
Returns:
status
content
id
username
name
avatar
points
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
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
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