Sequence Events Feed

Introduction

In order to track changes in resources, a client of the Sequence API can use the events feed.

Each event in the feed represents something relevant that happened on a specified resource at specified time.

Currently, entries in the feed are generated for three types of events per resource:

• The creation of the resource.
• The modification of any attribute or link of the resource.
• The deletion of the resource.

This is an example of the XML representation of the event feed:

<events type="array">
  <event>
    <id type="integer">40393</id>
    <event-type>job_created</event-type>
    <timestamp type="datetime">2012-12-03T09:35:37+00:00</timestamp>
    <link href="https://sequence/api/work_areas/85/jobs/97185" rel="subject"/>
  </event>
  <event>
    <id type="integer">40397</id>
    <event-type>asset_updated</event-type>
    <changes>status,name</changes>
    <timestamp type="datetime">2012-12-03T09:35:39+00:00</timestamp>
    <link href="https://sequence/api/work_areas/85/jobs/97185/assets/467237" rel="subject"/>
  </event>
  <event>
    <id type="integer">40401</id>
    <event-type>task_destroyed</event-type>
    <timestamp type="datetime">2012-12-04T14:46:55+00:00</timestamp>
    <link href="https://sequence/api/work_areas/85/jobs/97144/tasks/3030" rel="subject"/>
  </event>
</events>

Available attributes:

Event ID (id)

Integer: Read only

The identifier of the event. Events are presented sorted by id and can be filtered with the newer_than parameter (see below). Clients may want to store the id of the last processed event so that they don't process twice the same event.

Event Type (event-type)

String: Read only

The type of the event. The list of supported events is specified below. The format of the event-type is as follows:

{{resource_type}}_{{operation}}

Currently, there are three possible operations:

• created. For the creation of the resource.
• updated. For the modification of any attribute or link of the resource.
• deleted. For the deletion of the resource.

Changes (event-type)

Comma-separated string: Read only

The list of attributes and links that changed. This attribute is only present if the event-type is an _update. This list refers to the names of the changed attributes and to the "rels" of the links that have changed. To know what are the new values for those attributes or links, you'll have to follow the subject link.

Timestamp (timestamp)

Datetime: Read only

The date and time when the event occurred.

Available links:

Subject (subject)

The resource that was created, updated or deleted.

GETting the event feed

The event feed is linked from the root of the Sequence API:

$ curl --digest -u api_user http://sequence/api

<?xml version='1.0' encoding='utf-8' ?>
<sequence>
  <!-- ... -->
  <link href="http://sequence.local/api/events" rel="events"/>
</sequence>

Following the events link you'll get the event feed:

$ curl --digest -u api_user http://sequence/api/events

<?xml version='1.0' encoding='utf-8' ?>
<events type="array">
  <!-- ... -->
</events>

The event feed is limited to show no more than 50 events in timestamp ascending order (i.e. older events will appear first). You can navigate and filter the event feed using its GET parameters described in the following section.

Available GET parameters

Newer than (newer_than)

Integer: it can be used with any other parameter

This parameter can be used to fetch the events which are newer than another one. The value of this parameter shall be the id of the event taken as a reference.

For example: /api/events?newer_than=234 will return the events more recent than the event with id 234.

Typically, clients will store locally the id of the last id they have processed so that in the next processing only the events newer than the last processed one will be fetched.

Also, given that the event feed is limited to 50 entries, the newer_than parameter shall be used to navigate the feed until reaching the last page.

Event type filter (event_type)

Comma-separated string: it can be used with any other parameter

This parameter will allow clients to filter the feed to include only entries for certain event types. The value of this parameter shall be a list of event types separated by commas.

For example: /api/events?event_type=job_created,task_updated will return only events of which event_type is job_created or task_updated.

Clients are encouraged to use the event_type filter to fetch only those event types which are relevant to them, avoiding unnecessary processing.