Skip to content

Notification API

Jump to bottom Edit New page
Soumya Brahma edited this page Feb 4, 2016 · 5 revisions

Table of Contents

Motivation

Notifications will be generated by RODL whenever there are events related to Research Objects. Examples include:

  • A checklist service evaluation change. This can be a service that is down or a hypothesis added.
  • A resource that is a part of an RO is in an obsolete format and an update is recommended.
  • The workflow is no longer runnable according to the workflow runner...
Notifications will be available in an Atom format (similar to RSS), and clients will be able to poll them to check if there is anything new. If there is, they may show it to the user on a website, send an email, etc. The primary client will be myExperiment, which at some point will be able to poll these notifications and also provide options for users to subscribe to Research Objects/packs. Meanwhile, we may test the notification service using the RO Portal.

API Usage

Getting the notification feed

The clients can poll the notifications resource to get notifications. In order to ensure that they get all notifications they want, they can use the following options:

  • ro - the research object URI. If set, only notifications related to this RO will be returned.
  • from - the timestamp of the oldest notification that should be returned. The timestamp should be an ISO 8601 date time format (wikipedia).
  • to - the timestamp of the most recent notification that should be returned. The timestamp should be an ISO 8601 date time format (wikipedia).
  • source - URI of the producer of notifications.
  • limit - the maximum number of results to be returned.
If neither "from", "to" nor "limit" are set, the service should return no more than 10 notifications.

Finding related resources

Each notification is an Atom feed entry, which may have multiple link fields. Depending on the topic of the notification, the links may reference related research objects, checklist evaluation results, etc. Clients should follow them to obtain more data in machine-friendly formats (XML, JSON, RDF, etc).

Link relations

Used in the service description to point to the notification resource URI template.

Also used in the Research Object resource in the ?RO API 6 as a Link header to point to the notification resource of that particular RO.

Used in the feed entry (i.e. the notification) to link the feed with the Research Object it describes. Used in the feed entry (i.e. the notification) to link the feed with the checklist evaluation result that is related to it.

HTTP Methods

GET can be used to get the notifications. Notifications are read only, and no other method is available.

Resources and formats

Service description

This document is available in RDF/XML or Turtle format and contains the URI template for the notification resource. The client may create the notification URI by building the template with the following parameters:

ro - the research object URI. If set, only notifications related to this RO will be returned. from - the timestamp of the oldest notification that should be returned. to - the timestamp of the most recent notification that should be returned. source - URI of the producer of notifications. limit - the maximum number of results to be returned. If neither "from", "to" nor "limit" are set, the service should return no more than 10 notifications.

Notifications

The notifications are available as an Atom feed.

An example: 

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
	<title>Notifications for Research Object "myGenes"</title>
	<subtitle>Notifications between 2000-06-13T16:20:02Z and
		2006-06-13T16:20:02Z
	</subtitle>
	<!-- link to this feed -->
	<link
	href="http://example.org/rodl/notifications?ro=/rodl/ROs/myGenes/&from=2000-06-13T16:20:02Z&to=2006-06-13T16:20:02Z"
	="self" />
	<!-- link to RO -->
	<link href="http://example.org/rodl/ROs/myGenes/" rel="http://www.openarchives.org/ore/terms/describes" />
	<!-- id is the feed URI -->
	<id>http://example.org/rodl/notifications?ro=/rodl/ROs/myGenes/&from=2000-06-13T16:20:02Z&to=2006-06-13T16:20:02Z
	</id>
	<updated>2005-06-13T16:20:02Z</updated>
	<author>
		<name>Research Object Digital Library</name>
		<email>http://sandbox.wf4ever-project.org/rodl</email>
	</author>

	<!-- each entry is a notification -->
	<entry>
		<title>Quality improvement</title>
		<!-- link to RO, only if you ask for feeds for more than one RO (all ROs) -->
		<link href="http://example.org/rodl/ROs/myGenes/" rel="http://www.openarchives.org/ore/terms/describes" />
		<!-- the source of this notification is the checklist service -->
		<link href="http://sandbox.wf4ever-project.org/roevaluate/" rel="http://purl.org/dc/terms/source" />
		<!-- an internal entry id, consistent across different feeds -->
		<id>urn:X-rodl:13</id>
		<published>2005-06-13T16:20:02Z</published>
		<!-- here goes the notification message -->
		<summary type="html">&lt;p&gt;Lorem ipsum&lt;/p&gt;</summary>
	</entry>
</feed>

References

Add a custom footer

RO Services and APIs

Clone this wiki locally