M2A Schedule API (v1)

This endpoint supports listing all events for the specific owner. The following query parameters can be used to filter events:

• filter[interval]: list events which fall within specified time interval
• filter[end-time]: list events which end after the specified end time
• filter[enrolment]: list events linked to the enrolment with a specified type and with a specified id
• filter[mediainput]: list events linked to the mediainput with a specified type and with a specified id
• filter[id]: bulk-fetch events by id (see below)

Bulk fetch by id

filter[id] takes a comma-separated list of up to 100 event ids and returns those events for the specified owner. It follows the M2A bulk partial-success response format:

• The response is always 200 OK, regardless of how many ids could not be resolved.
• Successfully retrieved events are returned in the top-level data array.
• Ids which could not be resolved are returned in meta.errors, one entry per id, each with the requested id and an HTTP status code (as a string): 404 (no event with that id for this owner) or 403 (caller not permitted). For the full error detail, issue a targeted GET /events/{eventId}.
• If every id resolves, meta.errors is omitted or returned as an empty array. If none resolve, data is an empty array and meta.errors contains an entry for each id.
• Duplicate ids are de-duplicated; each unique id appears at most once in data and at most once in meta.errors.
• CANCELLED and ABORTED events are not deleted and are returned in data like any other event.
• A request with more than 100 ids returns 400 Bad Request.

{
  'data': [...],
  'meta': {
    'errors': [
      { 'id': '2e31a1e3-abd2-4bc5-9443-bc0c6acf36d7', 'status': '404' }
    ]
  }
}

filter[id] must be used independently of the other filters and is not paginated.

Query parameter fields[event] allows to specify which event attributes or relationships to include along with type and id in each event object in the list.

You can find more details about query parameters below.

The schedule events list is paginated. Each page contains up to 50 events.

The following structure is used for the response where data contains a list of event objects and next contains an url of the next page of events:

{
  'data': [...],
  'links': {
    'next': ...
  }
}

The endpoint for creating a schedule event.

Requirements for a valid request:

• Type must be specified as event.

• Attributes name, start-time, on-air-start-time, on-air-end-time, end-time, metadata must be included in payload.

• Event time value requirements:

  • the value of start-time must be earlier than on-air-start-time value,
  • on-air-start-time value must be earlier than on-air-end-time value,
  • on_air_end_time value must be earlier than end-time value

• Owner and at least one mediainput must be specified in payload relationships.

The default state for created event is CONFIRMED. Alternatively, DRAFT state can be specified in payload.

The endpoint for retrieving information about existing schedule event linked to a specific owner. Event id is required in path parameters and owner id is required in query parameters.

The endpoint for updating existing schedule event linked to a specific owner. Event id is required in path parameters and owner id is required in query parameters.

If-Match HTTP request header can be used to make a request conditional.

The minimum required data in request body is

  {
    'data': {
        'id': 'c49c499b-4e7e-4acb-ae83-f528b6ed194d',
        'type': 'event'
    }
  }

Event id parameter in path and event id in request body must match.

Updating attributes

The payload above won't change anything about the event. To change any event attribute value, it needs to be added to payload as part of event attributes. E.g., for changing just event's name:

  {
    'data': {
        'id': 'c49c499b-4e7e-4acb-ae83-f528b6ed194d',
        'type': 'event'
        'attributes': {
          'name': 'New name'
        }
    }
  }

In the case above all the other event attribute values will stay unchanged.

Updating relationships

For updating event's enrolment or mediainput list, the full list must be provided in the payload (with old and/or new enrolments/mediainputs):

  {
    'data': {
        'id': 'c49c499b-4e7e-4acb-ae83-f528b6ed194d',
        'type': 'event'
        'relationships': {
          'enrolments': {
            'data': [
              {
                'id': '7b465202-498d-4617-8212-607ead208b76',
                'type': 'source'
              }
            ]
          }
        }
    }
  }

For removing all event's enrolments, the empty list must be provided in the payload:

  {
    'data': {
        'id': 'c49c499b-4e7e-4acb-ae83-f528b6ed194d',
        'type': 'event'
        'relationships': {
          'enrolments': {
            'data': []
          }
        }
    }
  }

Mediainput list must have at least one mediainput linked to the event. It is not possible to update event's owner.

Requirements for changes to be valid

• It is not possible to update an event with a current state CANCELLED or ABORTED

• If event's current state is ENDED, it is possible to update only values for attributes:

  • name
  • description
  • metadata

• If changing event's state, valid transitions are:

  • CONFIRMED --> DRAFT
  • DRAFT --> CONFIRMED
  • CONFIRMED --> CANCELLED
  • DRAFT --> CANCELLED
  • PRE_TX --> ABORTED
  • TX --> ABORTED
  • POST_TX --> ABORTED

• if changing event's start-time, event's current state must be DRAFT OR current event's start-time must be in the future.

• if changing event's end-time, event's current state must be DRAFT OR current event's end-time must be in the future.

• Event time value requirements:

  • the value of start-time must be earlier than on-air-start-time value,
  • on-air-start-time value must be earlier than on-air-end-time value,
  • on_air_end_time value must be earlier than end-time value

Deletes a specific event by setting event's state to ABORTED or CANCELLED.

Possible state transitions:

• DRAFT --> CANCELLED
• CONFIRMED --> CANCELLED
• PRE_TX --> ABORTED
• TX --> ABORTED
• POST_TX --> ABORTED

It is not possible to delete an event with current state ABORTED, CANCELLED or ENDED.

If-Match HTTP request header can be used to make a request conditional.