Groups API

From StatusNet
Revision as of 17:13, 22 February 2012 by March (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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.

Contents

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 "!groupname" 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.

Groups API method list

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 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 "basic user information elements"
  • "basic user information elements" identical to Twitter API's [1]
  • Notices output as Twitter API "status elements" [2]

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 

<group>
  <id>8</id>
  <url>http://identi.ca/group/8/id<url>
  <nickname>ubuntu</nickname>
  <fullname>Ubuntu users</fullname>
  <original_logo>http://identi.ca/avatar/8-original-group-20090123170323.png</original_logo>
  <homepage_logo>http://identi.ca/avatar/34648-original-20090123170354.png</homepage_logo>
  <stream_logo>http://identi.ca/avatar/34648-original-20090123170431.png</stream_logo>
  <mini_logo>http://identi.ca/avatar/34648-original-20090123170456.png</mini_logo>
  <homepage>http://www.ubuntu.com/</homepage>
  <description>A view in to the lives of Ubuntu users</description>
  <location>Everywhere</location>
  <created>Fri Jan 23 10:33:41 +0000 2009</created>
  <modified>Fri Jan 23 10:33:41 +0000 2009</modified>
</group>

Tag element

tag

Example tag element XML 

<tag>something</tag>
Retrieved from "http://status.net/wiki/index.php?title=Groups_API&oldid=15288"
Personal tools
Namespaces
Variants
Actions
Navigation
Status.net
Toolbox