Plugin requirements

Plugin requirements

Plugins accept:

• A POST request containing, in the request header, a JSON-encoded set of artifact IDs along with synonyms, like this:

{
   <id>: {
      "url":<url>,
      "pmid":<pubmed id>
   },
   <id>: {
      "url":<url>,
      "pmid":<pubmed id>
   },
   ...
}

* For external plugins (running on other people's servers), the mechanics of this are not our concern.
* For local plugins, though, we need to handle the REST interface. To do this, Jason is replacing the old system with this one: each plugin is an appropriately-named directory. Each directory contains index.php, which for Python plugins will contain this:

$pluginName = "plugin.py";
$idsJsonStr = escapeshellarg($_POST);
echo exec('python ' . $pluginName . ' ' . $idsJsonStr);

This is nothing more than a wrapper that calls the Python code and prints the output. The advantage to this is that plugin writers fluent in Python can control the entire behaviour of their plugins, and there is clear division of responsibility. The plugin directory is entirely self-contained and calls no other code.

Plugins process

• filter those IDs so that only relevant ones are sent to Source API
• chunk them together if their Source API gets down like that
• make as many calls as needed to their Source API to get data on everything.
  • pause before each call, if needed to handle rate limiting (eg, for Delicious)
• do error checking on what they get back from the Source and handle things appropriately
  • Plugins should use exponential backoff to handle bad responses from Source APIs. For now, the maximum wait interval should be 5 minutes or so, then an error should be thrown.
  • For now, errors should be reported by returning a JSON object like this: {"error": "<text of error message>"}. In the future, we can use error codes.
  • In the future, plugins may want to cache responses
  • Plugins may want to log reponses

Plugins return

Plugins return a flat array of events, possibly of different types. Each event is an object with these attributes (note the addition of a timestamp, so we know how fresh it is and can gather others over time):

id: <artifact id>
source_name: <source name>
metric_name: <metric name; can be metadata like "title">
metric_value: <[string (eg, a title)] OR [int (0-∞)] OR [the special string "NA" to indicate no expected value (eg, you've sent Dryad IDs to Slideshare)]>
icon: <url for icon img>
type: <the type of the artifact, like "article" or "slides">
timestamp: <current UNIX timestamp in seconds>

Also, in the future, plugins respond to a special GET request with the "?register=true" flag sent, sending documentation about the plugin (I suggest this is a post-alpha project)