Skip to content

Developers

How can we help you?

← Go back

Event

In order to track changes in any resource (title, metadata, etc.) you can use the BeBanjo events feed.

Each entry in the feed represents a relevant event that happened on a specified resource at a 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/JSON representation of the event feed:

<events type="array">
  <event>
    <id type="integer">10</id>
    <event-type>title_updated</event-type>
    <timestamp type="datetime">2013-08-14T17:09:35+02:00</timestamp>
    <changes>episode-number</changes>
    <link rel="self" href="https://movida.bebanjo.net/api/events/10"/>
    <link rel="subject" href="https://movida.bebanjo.net/api/titles/114013"/>
  </event>
  <event>
    <id type="integer">12</id>
    <event-type>title_metadata_updated</event-type>
    <timestamp type="datetime">2013-08-14T17:40:01+02:00</timestamp>
    <changes>actor,director,first-tx-starts</changes>
    <link rel="self" href="https://movida.bebanjo.net/api/events/12"/>
    <link rel="subject" href="https://movida.bebanjo.net/api/titles/59977"/>
  </event>
  <!-- ... -->
</events>
{
  "entries": [
    {
      "resource_type": "event",
      "id": 10,
      "event_type": "title_updated",
      "timestamp": "2013-08-14T17:09:35+02:00",
      "changes": "episode-number",
      "self_link": "https://movida.bebanjo.net/api/events/10",
      "subject_link": "https://movida.bebanjo.net/api/titles/114013"
    },
    {
      "resource_type": "event",
      "id": 12,
      "event_type": "title_metadata_updated",
      "timestamp": "2013-08-14T17:40:01+02:00",
      "changes": "actor,director,first-tx-starts",
      "self_link": "https://movida.bebanjo.net/api/events/12",
      "subject_link": "https://movida.bebanjo.net/api/titles/59977"
    },
    // ...
  ]
}

Valid attributes

  • id (Event ID, integer, read only): The identifier of the event. Events are presented ordered by id and they can be filtered with the newer_than parameter (see below). You may want to store the id of the last processed event so that they don’t process twice the same event.

  • event-type (string, read only): The type of the event. The list of supported events is specified in a section 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 (comma-separated, string, read only): The list of attributes and links that changed. This attribute is only present if the event-type is *_update. This list refers to the names of the attributes and to the “rels” of the links of the resource that have changed. To know what are the new values for those attributes or links, you’ll have to follow the subject link.

  • timestamp (datetime, read only): The date and time when the event occurred.

  • subject: The resource that was created, updated or deleted.
  • source: The source associated to the event. Currently this link is only available for events of type scheduling_created.

Note: When trying to access the subject link of the events a HTTP response code of 404 (Not Found) might be returned. It means just that the requested resource cannot be found (because it has been deleted). Probably there will be a newer event of the type *_deleted (i.e. scheduling_deleted) in the feed pending to be processed.

Getting the event feed

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

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api
$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api
<?xml version='1.0' encoding='utf-8' ?>
<movida>
  <!-- ... -->
  <link rel="events" href="https://movida.bebanjo.net/api/events"/>
  <!-- ... -->
</movida>
{
  "resource_type": "movida",
  // ...
  "events_link": "https://movida.bebanjo.net/api/events",
  // ...
}

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

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/events
$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/events
<?xml version='1.0' encoding='utf-8' ?>
<events type="array">
  <!-- ... -->
</events>
{
  "entries": [
    // ...
  ]
}

The event feed is limited to show no more than 50 events in ascending order of their timestamps (i.e. older events will appear first). You can navigate and filter the event feed using the attributes described in the following section. If the parameter newer_than is not provided, the response will contain the last 50 events in ascending order of the current account.

You can also pass the following attributes in order to filter the event feed:

  • newer_than (integer, it can be used with any other parameter): This parameter filter the feed to include only events that are newer than another one. The value of this parameter will be the id of the event taken as a reference.

    For example: /api/events?newer_than=234 will return events more recent than the event 234. Typically, you may want to store locally the id of the last event you have processed so that in the next processing you only request the events newer than the last one you processed. Also, given that the event feed is limited to 50 entries, you should use the newer_than parameter to navigate the feed until reaching the last event.

  • event_type (string, comma-separated, 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 will be a list of event types separated by commas.

    For example: /api/events?event_type=title_updated,title_metadata_updated will return only events whose event_type is title_updated or title_metadata_updated. You are encouraged to use the event_type filter to fetch only those event types which are relevant to you, avoiding unnecessary processing. Currently the supported event types are:

    • asset_created
    • asset_deleted
    • asset_metadata_updated
    • asset_updated
    • audio_track_created
    • audio_track_deleted
    • audio_track_metadata_updated
    • audio_track_updated
    • availability_window_created
    • availability_window_deleted
    • availability_window_updated
    • brand_created
    • brand_deleted
    • brand_metadata_updated
    • brand_updated
    • contributor_created
    • contributor_deleted
    • contributor_metadata_updated
    • contributor_updated
    • credit_created
    • credit_deleted
    • credit_updated
    • deal_created
    • deal_deleted
    • deal_metadata_updated
    • deal_updated
    • granted_requirement_created
    • granted_requirement_deleted
    • granted_requirement_updated
    • image_created
    • image_deleted
    • image_metadata_updated
    • image_updated
    • linear_program_created
    • linear_program_updated
    • linear_program_deleted
    • linear_program_group_created
    • linear_program_group_updated
    • linear_program_group_deleted
    • platform_created
    • platform_deleted
    • platform_updated
    • publication_created
    • rendition_created
    • rendition_deleted
    • rendition_metadata_updated
    • rendition_updated
    • right_created
    • right_deleted
    • right_metadata_updated
    • right_updated
    • scheduling_created
    • scheduling_deleted
    • scheduling_metadata_updated
    • scheduling_updated
    • specific_platform_created
    • specific_platform_deleted
    • specific_platform_updated
    • subtitle_created
    • subtitle_deleted
    • subtitle_metadata_updated
    • subtitle_updated
    • target_platform_created
    • target_platform_updated
    • target_platform_deleted
    • title_created
    • title_deleted
    • title_group_created
    • title_group_deleted
    • title_group_metadata_updated
    • title_group_updated
    • title_metadata_updated
    • title_updated

Remember you can use the expand me some nodes trick if you want to, for instance, find out what were the parents of the event subject.

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/events?expand=subject
$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/events?expand=subject
<?xml version='1.0' encoding='utf-8' ?>
<events type="array">
  <event>
    <id type="integer">10</id>
    <event-type>rendition_deleted</event-type>
    <timestamp type="datetime">2019-05-28T02:26:22-07:00</timestamp>
    <link rel="self" href="https://movida.bebanjo.net/api/events/100"/>
    <link rel="subject" href="https://movida.bebanjo.net/api/renditions/1628494">
      <subject>
        <id type="integer">310411</id>
        <external-id>C5155250234</external-id>
        <link rel="self" href="https://movida.bebanjo.net/api/renditions/1628494"/>
        <link rel="asset" href="https://movida.bebanjo.net/api/assets/1787229"/>
      </subject>
    </link>
  </event>
  <!-- ... -->
</events>
{
  "entries": [
    {
      "resource_type": "event",
      "id": 10,
      "event_type": "rendition_deleted",
      "timestamp": "2019-05-28T02:26:22-07:00",
      "self_link": "https://movida.bebanjo.net/api/events/10",
      "subject_link": "https://movida.bebanjo.net/api/renditions/1628494",
      "subject": {
        "resource_type": "subject",
        "id": 310411,
        "external_id": "C5155250234",
        "self_link": "https://movida.bebanjo.net/api/renditions/1628494",
        "asset_link": "https://movida.bebanjo.net/api/assets/1787229"
      }
    },
    // ...
  ]
}

Note: The external-id attribute will only be present in the subject for those resources with a configurable external-id (i.e. Brand, Contributor, Deal, Image, Platform, Rendition, Scheduling and Title).

You can also use the expand me some nodes trick in order to get the details of the source associated to a scheduling created.

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/events?expand=source
$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/events?expand=source
<?xml version='1.0' encoding='utf-8' ?>
<events type="array">
  <event>
    <id type="integer">260325304</id>
    <event-type>scheduling_created</event-type>
    <timestamp type="datetime">2022-02-04T14:21:55+01:00</timestamp>
    <link rel="self" href="https://movida.bebanjo.net/api/events/260325304"/>
    <link rel="subject" href="https://movida.bebanjo.net/api/schedulings/14451796"/>
    <link rel="source" href="https://movida.bebanjo.net/api/rules/89304">
      <rule>
        <id type="integer">89304</id>
        <external-id>1185427274003-263-RR</external-id>
        <transmission-type>rerun</transmission-type>
        <reference-tx-nth>all</reference-tx-nth>
        <reference-tx-from type="datetime">2021-01-01T00:00:00+01:00</reference-tx-from>
        <reference-tx-to type="datetime">2022-12-31T00:00:00+01:00</reference-tx-to>
        <day-part-from nil="true"/>
        <day-part-to nil="true"/>
        <start-offset-value type="integer">0</start-offset-value>
        <start-offset-unit>days</start-offset-unit>
        <start-offset-reference>after_tx_starts</start-offset-reference>
        <start-fixed-time nil="true"/>
        <end-offset-value type="integer">30</end-offset-value>
        <end-offset-unit>days</end-offset-unit>
        <end-offset-reference>after_tx_ends</end-offset-reference>
        <end-fixed-time nil="true"/>
        <asset-selection-type nil="true"/>
        <link rel="self" href="https://movida.bebanjo.net/api/rules/89304"/>
        <link rel="content" href="https://movida.bebanjo.net/api/titles/2737934"/>
        <link rel="specific_platforms" href="https://movida.bebanjo.net/api/rules/89304/specific_platforms"/>
        <link rel="reference_tx_channel" href="https://movida.bebanjo.net/api/linear_channels/263"/>
      </rule>
    </link>
  </event>
  <!-- ... -->
</events>
{
  "entries": [
    {
      "resource_type": "event",
      "id": 260325304,
      "event_type": "scheduling_created",
      "timestamp": "2022-02-04T14:21:55+01:00",
      "self_link": "https://movida.bebanjo.net/api/events/260325304",
      "subject_link": "https://movida.bebanjo.net/api/schedulings/14451796",
      "source_link": "https://movida.bebanjo.net/api/rules/89304",
      "source": {
        "resource_type": "rule",
        "id": 89304,
        "external_id": "1185427274003-263-RR",
        "transmission_type": "rerun",
        "reference_tx_nth": "all",
        "reference_tx_from": "2021-01-01T00:00:00+01:00",
        "reference_tx_to": "2022-12-31T00:00:00+01:00",
        "day_part_from": null,
        "day_part_to": null,
        "start_offset_value": 0,
        "start_offset_unit": "days",
        "start_offset_reference": "after_tx_starts",
        "start_fixed_time": null,
        "end_offset_value": 30,
        "end_offset_unit": "days",
        "end_offset_reference": "after_tx_ends",
        "end_fixed_time": null,
        "asset_selection_type": null,
        "self_link": "https://movida.bebanjo.net/api/rules/89304",
        "content_link": "https://movida.bebanjo.net/api/titles/2737934",
        "specific_platforms_link": "https://movida.bebanjo.net/api/rules/89304/specific_platforms",
        "reference_tx_channel_link": "https://movida.bebanjo.net/api/linear_channels/263"
      }
    },
    // ...
  ]
}