Plugin requirements

Plugin requirements

Plugins accept:

A POST request containing, in the request header, a JSON-encoded set of artifact IDs along with synonyms.

• Example 1: This is from a fresh collection that doesn't have any URL, DOI, or PMID info yet.
• Example 2: This is from a collection that does have synonym info, and these are listed as values under the appropriate fields.

in POST (a doi and a slideshare deck):

{"10.1371/journal.pcbi.1000361": {"url": "FALSE", "pmid": "FALSE", "doi": "10.1371/journal.pcbi.1000361"}, "http://www.slideshare.net/phylogenomics/eisen": {"url": "http://www.slideshare.net/phylogenomics/eisen", "pmid": "FALSE", "doi": "FALSE"}}

> >Return value from the Mendeley plugin (it only knows about dois): > >{"about": {"metrics": {"groups": "the number of groups of the article", "readers": "the number of readers of the article"}, "url": "http://www.mendeley.com/", "icon": "http://www.mendeley.com/favicon.ico", "desc": "A research management tool for desktop and web."}, "source_name": "Mendeley", "artifacts": {"10.1371/journal.pcbi.1000361": {"type": "article", "groups": 2, "readers": 31}}, "error_msg": "NA", "has_error": "FALSE", "last_update": "1315917142"}

For external plugins (running on other people's servers), the mechanics of accepting requests is not our concern. For local plugins, though, we need to handle the REST interface. To do this, each plugin is an appropriately-named directory.

Plugins process

• filter those IDs so that only relevant ones are sent to Source API
• for each relevant ID, note what type of artifact it is (article, slideshow, etc)
• 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 30 seconds or so, then an error should be thrown.
  • Errors are reported in the appropriate field in the response object
  • In the future, plugins may want to cache responses
  • Plugins may want to log reponses

Plugins return

An annotated example of a plugin should return here, in the test directory. This is what I unit test against, so if you conform to this, you're all good (actually the comments are invalid JSON, but other than that it's a real example).

Remember, there are three things that plugins can give back:

• counts of things (eg, "10 readers") is represented as an integer
• the things themselves (eg, an array of tweets, each with its own metadata) is an array
• artifact metadata (eg, its title) is represented as a string

All of these can be accommodated within the present structure; each artifact gets a bunch of key:value pairs encoding one of these. This way the same plugin can return different return types.