APIs

From Plnwiki

Revision as of 20:48, 8 January 2014 by Mjordan (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

SOAP APIs

(Added in LOCKSS v1.61)

LOCKSS offers two SOAP APIs, DaemonStatusService and CounterReportsService. Information on endpoints and the WSDL files for both are available at http://lockssbox.example.com:8081/ws.

Everything on port 8081 is protected by username/password and IP whitelisting. Therefore, to access the SOAP APIs you will need to 1) add the IP address of the computer running this script to the "Allow Access" list under "Admin Access Control" in your box's admin UI and 2) tell the SOAP client the username and password of the LOCKSS user. You do not need to (and probably shouldn't) use the admin user's account to access the SOAP service; instead, create a new user and give them only "View debug info" permissions.

A version of the first script below, plus some additional scripts, are available at https://github.com/mjordan/lockssscripts.

DaemonStatusService


<?php

/**
 * PHP code illustrating how to query the LOCKSS DaemonStatusService SOAP
 * API for a list of all AUs, and then retrieve information about each one.
 */

// Set up the SOAP client.
$client = new SoapClient("http://your.lockss.box.org:8081/ws/DaemonStatusService?wsdl",
  array('login' => "SOAPuser", 'password' => "xxxxxxx"));

// Check to see if the SOAP API says the daemon is ready.
$ready = $client->isDaemonReady();
if (!$ready) {
  die("LOCKSS daemon is not responding\n");
}

// Get a list of all the AU IDs.
$aus = $client->getAuIds();
if (count($aus) === 0) {
  die("No AUs found\n");
}

// Loop through the list and retrieve info about each one.
foreach ($aus->return as $au) {
  if (is_object($au)) {
    if (strlen($au->id)) {
      try {
        // Make the call to the getAuStatus() function.
        $status = $client->getAuStatus(array('auId' => $au->id));
        // Print out the returned data.
        print "\n\nauId: " . $au->id . "\n";
        print "Properties:\n";
        foreach ($status->return as $key => $value) {
           print "  $key => $value\n";
        }
      }
      catch (SoapFault $e) {
        print_r($e);
      }
    }
  }
}

?>


produces output like this for each AU in your LOCKSS box:


auId:  org|lockss|plugin|ojs2|OJS2Plugin&base_url~http%3A%2F%2Fjournals%2Euvic%2Eca%2F& journal_id~appeal&year~1996
Properties:
 accessType => Subscription
 availableFromPublisher => 1
 contentSize => 458724
 crawlPool => org.lockss.plugin.ojs2.OJS2Plugin
 creationTime => 1308074972000
 currentlyCrawling => 
 currentlyPolling => 
 diskUsage => 2547712
 journalTitle => Appeal: Review of Current Law and Law Reform
 lastCompletedCrawl => 1384247894638
 lastCompletedPoll => 1340367478816
 lastCrawl => 1384247876601
 lastCrawlResult => Successful
 lastPoll => 1384167807407
 lastPollResult => No Quorum
 pluginName => Open Journals System Plugin (OJS 2.x)
 publisher => University of Victoria
 recentPollAgreement => 0.9743589758873
 repository => /cache2/gamma/cache/dl/
 status => 100.00% Agreement
 substanceState => No
 volume => Appeal: Review of Current Law and Law Reform Volume 2 [tables of contents only]
 year => 1996

Legacy APIs

(In the process of becoming deprecated by newer SOAP APIs)

Daemon status information can be retrieved from the following endpoint:

http://<host>:8081/DaemonStatus?arg1=value&arg2=value&...

The query args (all optional) are:

Name Description
table Name of the table. Defaults to "OverviewStatus".
key A filter or name of an individual object to display, depending on the table.
options Pass "norows" to cause tabular data to be omitted from the response. Only the summary information will be returned.
output Output format. Valid values are: "html", "xml", "text", "csv". Defaults to "html".
columns Comma-separated list of columns to include. This mostly only affects HTML output.
sort Specifies sort key. Name of a column, prefaced by "A" (ascending) or "D" (descending), or two such specs separated by comma (primary and secondary sort). Affects only html output. Column names are internal symbols; the easiest way to find them is to display a table and hover over a column name).
outputVersion Pass "2" to request no formatting of output values (some exceptions apply).

Top-level tables do not require a "key" to be passed. A list of all the top-level tables can be retrieved by passing "table=table_of_all_tables".

For all other tables, the interpretation of the "key" argument varies from table to table as follows:

Table How the "key" arg is interpreted
AuIds "plugin:<pluginId>" - filters by plugin.
Plugins pluginId - displays details of that plugin
crawl_status_table auId - filters by AU.
crawl_urls "<crawl_number>.<type>", where <type> is one of "fetched", "error", "not modified", "parsed", "pending", "excluded", mime-type", and <crawl_number> is an index into the crawls table.
single_crawl_status_table crawl_numver - index into crawls table.
MetadataStatusErrorInfoTable Start time of entry to display in detail.
RepositoryTable Name of repository to filter by.
V3PollerDetailTable

V3AgreeURLsTable

V3DisagreeURLsTable

V3TooCloseURLsTable

V3ActiceRepairsTable

V3CompletedRepairsTable

Poll Id.
ArchivalUnitTable AuId.