Groups API

'''Update May 2010: Most of these proposals are implemented as of 0.9.2. The page needs to be updated to move docs on implemented features to the main docs, and see what needs to still be done.'''

The purpose of this document is to flesh out a mini-spec for our groups API. Eventually it could be re-purposed as actual documentation.

General notes

 * API calls for streams/lists output xml, json, rss, and atom. Commands and other calls that return single objects, only output xml or json. Append `.xml`, `.json`, `.rss`, or `.atom` where indicated by `format`.
 * Posting to a group is accomplished with the normal `/api/statuses/update.format` method using &quot;!groupname&quot; syntax anywhere in the status text.
 * All dates are returned in Twitter's custom date format as with the Twitter-compatible API methods.
 * id parameters can usually be specified as part of the URL (e.g.: `/api/statusnet/groups/list/id.format`) instead of as part of the request. If id is specified in both the url and in the request, the id from the request will be used.

list_all
List the 20 most recently created groups.


 * URL: `/api/statusnet/groups/list_all.format`
 * Method: GET
 * Auth required: no
 * Parameters:
 * page. Optional.
 * count. Optional. Number of groups to return. Max 200.
 * since. Optional. Narrow the results to groups created after the HTTP-formatted date.
 * before. Optional. Narrow the results to groups created before the HTTP-formatted date.
 * Formats: xml, json, rss, atom
 * Returns: a list of group profile elements

list
List the 20 most recent groups a user has joined. If the 'id' parameter is not specified it will return the authenticated user's groups.


 * URLs: `/api/statusnet/groups/list.format` or `/api/statusnet/groups/list/id.format`
 * Method: GET
 * Auth required: no
 * Parameters:
 * id. Optional. Can either be a nickname or numeric ID.
 * page. Optional.
 * count. Optional. Number of groups to return. Max 200.
 * since. Optional. Narrow the results to groups created after the HTTP-formatted date.
 * before. Optional. Narrow the results to groups created before the HTTP-formatted date.
 * Formats: xml, json, rss, atom
 * Returns: list of group profile elements

show
Returns a single group profile specified by an ID or name.


 * URLs: `/api/statusnet/groups/show.format` or `/api/statusnet/groups/show/id.format`
 * Method: GET
 * Auth required: no
 * Parameters:
 * id. Required.  The nickname or numerical ID of the group to show.
 * Formats: xml, json
 * Returns: group profile element

timeline
Show the 20 most recent notices for a particular group, specified by group name or ID.


 * URLs: `/api/statusnet/groups/timeline.format` or `/api/statusnet/groups/timeline/id.format`
 * Method: GET
 * Auth required: no
 * Parameters:
 * id. Required. The nickname or numeric ID of a group.
 * page. Optional.
 * count. Optional. Number of groups to return. Max 200.
 * since. Optional. Narrow the results to groups created after the HTTP-formatted date.
 * before. Optional. Narrow the results to groups created before the HTTP-formatted date.
 * since_id. Optional. Narrow the results to groups created after the specified group id.
 * before_id. Optional. Narrow the results to groups created before the specified group id.
 * Formats: xml, json, rss, atom
 * Returns: list of status elements

membership
List a group's members. List 20 newest members of the group specified by name or ID.


 * URLs: `/api/statusnet/groups/membership.format` or `/api/statusnet/groups/membership/id.format`
 * Method: GET
 * Auth required: no
 * Parameters:
 * id. Required. The nickname or numeric ID of a group.
 * page. Optional.
 * count. Optional. Number of groups to return. Max 200.
 * since. Optional. Narrow the results to members added since the HTTP-formatted date.
 * before. Optional. Narrow the results to members added before the HTTP-formatted date.
 * Formats: xml, json, rss, atom
 * Returns: list of basic user information elements

join
Join a group. Adds the authenticated user to a group. Returns an error message if the user is already member.


 * URLs: `/api/statusnet/groups/join.format` or `/api/statusnet/groups/join/id.format`
 * Method: POST
 * Auth required: yes
 * Parameters:
 * id. Required. The nickname or numeric ID of the group to join.
 * Formats: xml, json
 * Returns: a group profile element

leave
Leave a group. Removes the authenticated user from a group specified by name or ID. Returns an error message if the user is not a member.


 * URLs: `/api/statusnet/groups/leave.format` or `/api/statusnet/groups/leave/id.format`
 * Method: POST
 * Auth required: yes
 * Parameters:
 * id. Required. The nickname or numeric ID of the group to join.
 * Formats: xml, json
 * Returns: a group profile element

is_member
Tests to see whether a user is a member of a group.


 * URL: `/api/statusnet/groups/is_member.format`
 * Method: GET
 * Auth required: no
 * Parameters:
 * user_id. Required. Nickname or ID of the user to test.
 * group_id. Required. Nickname or ID of the group to test.
 * Formats: xml, json
 * Returns: true, false

create
Make a new group. Sets the authenticated user as the administrator of the group.


 * URL: `/api/statusnet/groups/create.format`
 * Method: POST
 * Auth required: yes
 * Parameters:
 * nickname. Required.
 * full_name. Optional.
 * homepage. Optional.
 * description. Optional. 140c or less description of the group.
 * location. Optional.
 * aliases. Optional. Extra nicknames for the group, comma- or space- separated
 * Formats: xml, json
 * Returns: a group profile element

update
Update an existing group. Returns an error message if the authenticated user is not the administrator of the group being modified.


 * URL: `/api/statusnet/groups/update.format` or `/api/statusnet/groups/update/id.format`
 * Method: POST
 * Auth required: yes
 * Parameters:
 * id. Required. The nickname or numeric ID of the group to update.
 * nickname. Optional.
 * full_name. Optional.
 * homepage. Optional.
 * description. Optional. 140c or less description of the group.
 * location. Optional.
 * aliases. Optional. Extra nicknames for the group, comma- or space- separated, max 3
 * Formats: xml, json
 * Returns: a group profile element

update_group_logo
Update the logo for a group. Expects raw multipart data, not a URL to an image. Returns an error message if the authenticated user is not the administrator of the group being modified.


 * URLs: `/api/statusnet/groups/update_group_logo.format` or `/api/statusnet/groups/update_group_logo/id.format`
 * Methods: POST
 * Auth required: yes
 * Formats: xml, json
 * parameters:
 * id. Required. The nickname or numeric ID of the group to update.
 * image. Required. Must be a valid GIF, JPG, or PNG image of size defined by ImageFile::maxFileSize.
 * Returns: group profile element

destroy
Delete a group specified by a name or ID. Returns an error message if the authenticated user is not the administrator of the group being destroyed.


 * URLs: `/api/statusnet/groups/destroy.format` or `/api/statusnet/groups/destroy/id.format`
 * Methods: POST, DELETE
 * Auth required: yes
 * Parameters:
 * id. Required. The nickname or numeric ID of the group to destroy.
 * Formats: xml, json
 * Returns: group profile element

tags
List tags used in a group specified by a name or ID.


 * URLs: `/api/statusnet/groups/tag.format` or `/api/statusnet/groups/tag/id.format`
 * Method: GET
 * Auth required: No
 * Parameters:
 * id. Required. The nickname or numeric ID of the group to show tags for.
 * page. Optional.
 * Formats: xml, json, rss, atom
 * Returns: a list of tag elements

Object representations / return elements

 * Group profile fields similar to Twitter's &quot;basic user information elements&quot;
 * &quot;basic user information elements&quot; identical to Twitter API's
 * Notices output as Twitter API &quot;status elements&quot;

Group element
group id url nickname fullname member_count original_logo homepage_logo stream_logo mini_logo homepage description location created modified

Example group profile element XML
8 http://identi.ca/group/8/id ubuntu Ubuntu users http://identi.ca/avatar/8-original-group-20090123170323.png http://identi.ca/avatar/34648-original-20090123170354.png http://identi.ca/avatar/34648-original-20090123170431.png http://identi.ca/avatar/34648-original-20090123170456.png http://www.ubuntu.com/ A view in to the lives of Ubuntu users Everywhere Fri Jan 23 10:33:41 +0000 2009 Fri Jan 23 10:33:41 +0000 2009

Tag element
tag

Example tag element XML
something