--- name: "Socialtext::Resting" section: "3pm" platform: "linux" package: "libsocialtext-resting-perl" version: "0.38-1" release: "Debian 7 (Wheezy)" platforms: ["linux"] url: "https://new.carta.tech/Socialtext::Resting" --- # Socialtext::Resting(3pm) module for accessing Socialtext REST APIs ## 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. ### get\_backlinks ``` $Rester->workspace('wikiname'); $Rester->get_backlinks('page_name'); ``` List all backlinks to the specified page ### get\_frontlinks ``` $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 targeting 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 `""` Kevin Jones `""` Brandon Noard `""` ### CONTRIBUTORS Luke Closs Jeremy Stashewsky Chris Dent Kirsten Jones Michele Berg - *get\_revisions()*