SOAP is here, wash yourself

Journals now support SOAP. This is experimental and subject to change, though I hope that it won't change significantly, except to fix bugs and improve in various ways.

There are five methods.

• add_entry(LIST)
  add_entry(SUBJECT, BODY)

  Add an journal entry. Either pass two arguments, SUBJECT and BODY, or pass a list of key-value pairs, where the allowed keys are subject, body, discuss, posttype, tid.

  discuss is a boolean for turning on discussions. posttype is an integer specifying one of the allowed post types. tid is an integer specifying the one of the topic IDs (topics aren't really used in journals on use.perl.org right now). These things will take your defaults if left unspecified.

  Method returns the unique ID of the new entry, or false for failure.

• modify_entry(ID, LIST)

  Similar to add_entry, but modifies an existing entry, specified by ID. Journal ID can also be seen in the header of the particular journal entry in the web interface. Supply only the keys that are to be modified.

  Method returns the same unique ID if successful, or false for failure.

• delete_entry(ID)

  Deletes entry specified by given ID.

  Returns true for success, false for failure.

• get_entry(ID)

  Returns hashref with data for given entry, or false for failure.

  Data currently includes the URL to the journal entry, the URL to the journal discussion, the ID of the journal, the ID of the journal discussion, the body, the subject, the posting date, the topic ID, the user ID, the user nickname, and the posttype.

• get_entries(UID, LIMIT)

  Returns arrayref of hashrefs, with data for journal entries for user with given UID, or false for failure. Returns most recent LIMIT number of entries, with three keys for each entry: URL to the journal entry, the ID of the journal, and the subject.

Now, how to use it? I gave an example recently, but here is another. Note that I use SOAP::Lite (although any SOAP client should work) and I use my own local Netscape cookie file on Mac OS to provide authentication. If you don't properly authenticate, you will be able to use the get_* methods, but not the others; and, of course, you can only add/modify/delete your own entries.

#!/usr/bin/perl -w
use strict;
use HTTP::Cookies;
use SOAP::Lite;

my $host        = 'use.perl.org';
my $uri         = "http://$host/Slash/Journal/SOAP";
my $proxy       = "http://$host/journal.pl";
my $cookie_file = "$ENV{HOME}Netscape Users:Chris Nandor:MagicCookie";

my $cookie_jar  = HTTP::Cookies::Netscape->new;
$cookie_jar->load($ cookie_file);

my $journal = SOAP::Lite->uri($uri)
                        ->proxy($proxy, cookie_jar => $cookie_jar);

# now, the methods

my $recents = $journal->get_entries( 1, 10 )->result;
my $recent  = $journal->get_entry( $recents->[0]{id} )->result;

my $new_id  = $journal->add_entry( 'this is a test again', 'ha!' )->result;
$journal->modify_entry( $new_id, body => 'uh!' );

# this one is dangerous, be careful
# $journal->delete_entry( $new_id );

__END__

I hope this makes your journal experience a more pleasurable one. Note that you shouldn't abuse this by making a ton of entries, because I'll be angry, and so will your fellow users who are set to receive a message each time you post a new entry.

Two more things: there currently is no nickname->uid mapping (although get_entry returns the nickname and uid). There will be at some point, probably. Also, the only way to get recent journals is via RSS, which may suit whatever evil purposes you have.

Special thanks to jjohn for his help in figuring some of this stuff out.