The Perl Toolchain Summit 2025 Needs You: You can help 🙏 Learn more

 / 
Socialtext-Resting-0.38
River stage one • 5 direct dependents • 5 total dependents
/ Socialtext::Resting

NAME

Socialtext::Resting - module for accessing Socialtext REST APIs

SYNOPSIS


            

              
              
use Socialtext::Resting;
my $Rester = Socialtext::Resting->new(
  username => $opts{username},
  password => $opts{password},
  server   => $opts{server},
);
$Rester->workspace('wikiname');
$Rester->get_page('my_page');
}

DESCRIPTION

Socialtext::Resting is a module designed to allow remote access to the Socialtext REST APIs for use in perl programs.

METHODS

new


            

              
              
my $Rester = Socialtext::Resting->new(
    username => $opts{username},
    password => $opts{password},
    server   => $opts{server},
);
or
my $Rester = Socialtext::Resting->new(
    user_cookie => $opts{user_cookie},
    server      => $opts{server},
);

Creates a Socialtext::Resting object for the specified server/user/password, or server/cookie combination.

accept


            

              
              
$Rester->accept($mime_type);

Sets the HTTP Accept header to ask the server for a specific representation in future requests.

Standard representations: http://www.socialtext.net/st-rest-docs/index.cgi?standard_representations

Common representations:

text/x.socialtext-wiki
text/html
application/json

get_page


            

              
              
$Rester->workspace('wikiname');
$Rester->get_page('page_name');

Retrieves the content of the specified page. Note that the workspace method needs to be called first to specify which workspace to operate on.

get_page_revision


            

              
              
$Rester->workspace('wikiname');
$Rester->get_page_revision('page_name', 'revision_id');

Retrieves the content of the specified page revision. Note that the workspace method needs to be called first to specify which workspace to operate on.

get_attachment


            

              
              
$Rester->workspace('wikiname');
$Rester->get_attachment('attachment_id');

Retrieves the specified attachment from the workspace. Note that the workspace method needs to be called first to specify which workspace to operate on.

put_workspacetag


            

              
              
$Rester->workspace('wikiname');
$Rester->put_workspacetag('tag');

Add the specified tag to the workspace.

put_pagetag


            

              
              
$Rester->workspace('wikiname');
$Rester->put_pagetag('page_name', 'tag');

Add the specified tag to the page.

delete_workspacetag


            

              
              
$Rester->workspace('wikiname');
$Rester->delete_workspacetag('tag');

Delete the specified tag from the workspace.

delete_pagetag


            

              
              
$Rester->workspace('wikiname');
$Rester->delete_pagetag('page_name', 'tag');

Delete the specified tag from the page.

post_attachment


            

              
              
$Rester->workspace('wikiname');
$Rester->post_attachment('page_name',$id,$content,$mime_type);

Attach the file to the specified page

post_comment


            

              
              
$Rester->workspace('wikiname');
$Rester->post_comment( 'page_name', "me too" );

Add a comment to a page.

put_page


            

              
              
$Rester->workspace('wikiname');
$Rester->put_page('page_name',$content);

Save the content as a page in the wiki. $content can either be a string, which is treated as wikitext, or a hash with the following keys:

content

A string which is the page's wiki content.

date

RFC 2616 HTTP Date format string of the time the page was last edited

from

A username of the last editor of the page. If the the user does not exist it will be created, but will not be added to the workspace.

delete_page


            

              
              
$Rester->workspace('wikiname');
$Rester->delete_page('page_name');

Delete the specified page.

name_to_id


            

              
              
my $id = $Rester->name_to_id($name);
my $id = Socialtext::Resting::name_to_id($name);

Convert a page name into a page ID. Can be called as a method or as a function.

get_pages


            

              
              
$Rester->workspace('wikiname');
$Rester->get_pages();

List all pages in the wiki.

get_page_attachments


            

              
              
$Rester->get_page_attachments($page)

List all the attachments on a page.

get_sheet_cell


            

              
              
$Rester->get_sheet_cell($page_id, $cellid)

Get the value of a cell in a spreadsheet.

get_revisions


            

              
              
$Rester->get_revisions($page)

List all the revisions of a page.

get_taghistory


            

              
              
$Rester->workspace('wikiname');
$Rester->get_taghistory($page)

Get a history, by revision, of all tags for a page.

get_workspace_tags


            

              
              
$Rester->workspace('foo');
$Rester->get_workspace_tags()

List all the tags in workspace foo.

get_homepage

Return the page name of the homepage of the current workspace.


            

              
              
$Rester->workspace('wikiname');
$Rester->get_backlinks('page_name');

List all backlinks to the specified page


            

              
              
$Rester->workspace('wikiname');
$Rester->get_frontlinks('page_name');

List all 'frontlinks' on the specified page

get_pagetags


            

              
              
$Rester->workspace('wikiname');
$Rester->get_pagetags('page_name');

List all pagetags on the specified page

get_taggedpages


            

              
              
$Rester->worksapce('wikiname');
$Rester->get_taggedpages('tag');

List all the pages that are tagged with 'tag'.

get_tag


            

              
              
$Rester->workspace('wikiname');
$Rester->get_tag('tag');

Retrieves the specified tag from the workspace. Note that the workspace method needs to be called first to specify which workspace to operate on.

get_breadcrumbs


            

              
              
$Rester->get_breadcrumbs('workspace')

Get breadcrumbs for current user in this workspace

get_workspace


            

              
              
$Rester->get_workspace();

Return the metadata about a particular workspace.

get_workspaces


            

              
              
$Rester->get_workspaces();

List all workspaces on the server

get_user


            

              
              
my $userinfo = $Rester->get_user($username);
print $userinfo->{email_address};

Get information about a username

create_user


            

              
              
$Rester->create_user( { username => $username,
                        email_address => $email,
                        password => $password } );

Create a new user. Other parameters can be specified, see POD for Socialtext::User. username is optional and will default to the email address, as in most cases username and email_address will be the same.

add_user_to_workspace


            

              
              
$Rester->add_user_to_workspace( $workspace, { username => $user, 
                                  rolename => $role,
                                  send_confirmation_invitation => 0 || 1,
                                  from_address => $from_email } );

Add a user that already exists to a workspace. rolename defaults to 'member', send_confirmation_invitation defaults to '0'. from_address must refer to a valid existing user, and is only needed if send_confirmation_invitation is set to '1'. If the user is already a member of the workspace, this will reset their role if you specify a role that's different from their current role.

get_users_for_workspace


            

              
              
my @users = $Rester->get_users_for_workspace( $workspace );
for ( @users ) { print "$_->{name}, $_->{role}, $->{is_workspace_admin}\n" }

Get a list of users in a workspace, and their roles and admin status.

put_persontag


            

              
              
$Rester->put_persontag( $person, $tag )

Tag a person.

get_persontags


            

              
              
$Rester->get_persontags($person);

Retrieves all tags for a person

get_people


            

              
              
$Rester->get_people();

Retrieves all people.

get_person


            

              
              
$Rester->get_person();

Retrieves a person.

get_signals


            

              
              
$Rester->get_signals();
$Rester->get_signals(group_id => 42);
$Rester->get_signals(account_id => 2);

Retrieves the list of signals.

Optional arguments are passed as query paramaters.

post_signal


            

              
              
$Rester->post_signal('O HAI');
$Rester->post_signal('O HAI', group_id => 42);
$Rester->post_signal('O HAI', group_ids => [2,3,4]);
$Rester->post_signal('O HAI', account_id => 42);
$Rester->post_signal('O HAI', account_ids => [2,3,4]);
$Rester->post_signal('O HAI', in_reply_to => { signal_id => 142 });

Posts a signal.

Optional account_ids and group_ids arguments for targetting the signal.

Optional in_reply_to_id for specifying a signal_id this signal is in reply to.

Optional annotations to annotate the signal. annotations should be an array ref containing hashrefs that have one key (the annotation type) and a value that is a hashref containing key/value pairs.

post_webhook


            

              
              
$Rester->post_webhook( %args )

Creates a webhook. Args will be encoded as JSON and put up.

get_webhooks


            

              
              
my $hooks = $Rester->get_webhooks();

Returns an arrayref containing hashrefs of each webhook on the server.

delete_webhook


            

              
              
$Rester->delete_webhook( id => $webhook_id );

Deletes the specified webhook.

response


            

              
              
my $resp = $Rester->response;

Return the HTTP::Response object from the last request.

AUTHORS / MAINTAINERS

Shawn Devlin <shawn.devlin@socialtext.com>

Kevin Jones <kevin.jones@socialtext.com>

Brandon Noard <brandon.noard@socialtext.com>

CONTRIBUTORS

Luke Closs

Jeremy Stashewsky

Chris Dent

Kirsten Jones

Michele Berg - get_revisions()