API docs by Redocly

M2A Schedule API (v1)

Download OpenAPI specification:Download

Product Team: ta@m2amedia.tv URL: https://www.m2amedia.tv/ License: MIT

The M2A Schedule API replaces the Events API (see https://cloud.m2amedia.tv/docs/html/connect/events.html) to allow for additional resource types to be scheduled.

Terminology:

  • An event is a period of time during which resources need to be activated. An event has a start and an end time, and, an On Air start and end time
  • An enrolment is an M2A resource that can be managed by the schedule. Current supported resource types are source and workflow. Additonal resource types will be added in the future as they are deployed. One or more resources may be enrolled in an event.
  • A mediainput identifies logical media input to the event and is used to order the events on the vertical axis of the schedule view. Currently only a M2A Connect Source is supported, and the values for mediainput will be the same as the list of enrolments. In the future, the console view will be updated to allow different resource types to be modelled as the media input - ie an M2A Connect output.

API users can perform CRUD operations to manage events in the schedule.

API Structure:

The API is modelled on JSONAPI (https://jsonapi.org/format/). Where possible related resources are modelled as Relationships. ie:

  • a specific account owner (one to one relationship)
  • mediainputs (one to many relationship)
  • enrolments (one to many relationship)

Owner can be only of type target-account. Each mediainput and enrolment must be of type source or workflow. Each mediainput and enrolment must exist for this owner otherwise resource not found error will occur.

HTTP Headers:

The following headers are required for all requests -

{
  'Accept': 'application/vnd.api+json',
  'Content-Type': 'application/vnd.api+json'
}

Event Objects

The following structure is used for schedule event object:

{
  'data': {
    'type': 'event',
    'attributes': {...},
    'relationships': {
      'enrolments': {
        'data': [
          {
            'id': ...,
            'type': ...
          }
        ]
      },
      'mediainputs': {
        'data': [
          {
            'id': ...,
            'type': ...
          }
        ]
      }
      'owner': {
        'data': {
          'id': ...,
          'type': 'target-account'
        }
      }
    }
  }
}

Schedule event attributes are described in more detail below.

Events

Endpoints to perform CRUD (create, read, update, delete) operations on schedule events.

events

List events

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

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': ...
  }
}
Authorizations:
http_security_schema
query Parameters
owner
required
string <uuid> (Resource identifier)
Example: owner=c49c499b-4e7e-4acb-ae83-f528b6ed194d

The id of the target account

object

Event list filters

object

Sparse fields

header Parameters
Content-Type
required
string (JSON API)
Value: "application/vnd.api+json"

The original media type of the resource.

Accept
required
string (JSON API)
Value: "application/vnd.api+json"

Content type (expressed as MIME types) the client is able to understand.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "links": {
    },
  • "data": [
    ]
}

Create an event

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.

Authorizations:
http_security_schema
header Parameters
Content-Type
required
string (JSON API)
Value: "application/vnd.api+json"

The original media type of the resource.

Accept
required
string (JSON API)
Value: "application/vnd.api+json"

Content type (expressed as MIME types) the client is able to understand.

Request Body schema: application/vnd.api+json
required
object (Primary data)

Primary data with an event request body.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Info for a specific event

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.

Authorizations:
http_security_schema
path Parameters
eventId
required
string <uuid> (Resource identifier)
Example: c49c499b-4e7e-4acb-ae83-f528b6ed194d

The id of the event to retrieve

query Parameters
owner
required
string <uuid> (Resource identifier)
Example: owner=c49c499b-4e7e-4acb-ae83-f528b6ed194d

The id of the target account

header Parameters
Content-Type
required
string (JSON API)
Value: "application/vnd.api+json"

The original media type of the resource.

Accept
required
string (JSON API)
Value: "application/vnd.api+json"

Content type (expressed as MIME types) the client is able to understand.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Update an event

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
Authorizations:
http_security_schema
path Parameters
eventId
required
string <uuid> (Resource identifier)
Example: c49c499b-4e7e-4acb-ae83-f528b6ed194d

The id of the event to retrieve

query Parameters
owner
required
string <uuid> (Resource identifier)
Example: owner=c49c499b-4e7e-4acb-ae83-f528b6ed194d

The id of the target account

header Parameters
If-Match
string <uuid> (Resource identifier)
Example: c49c499b-4e7e-4acb-ae83-f528b6ed194d

Event ETag

Content-Type
required
string (JSON API)
Value: "application/vnd.api+json"

The original media type of the resource.

Accept
required
string (JSON API)
Value: "application/vnd.api+json"

Content type (expressed as MIME types) the client is able to understand.

Request Body schema: application/vnd.api+json
required
required
object (Primary data)

Primary data with an event request body.

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Deletes a specific event

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.

Authorizations:
http_security_schema
path Parameters
eventId
required
string <uuid> (Resource identifier)
Example: c49c499b-4e7e-4acb-ae83-f528b6ed194d

The id of the event to retrieve

query Parameters
owner
required
string <uuid> (Resource identifier)
Example: owner=c49c499b-4e7e-4acb-ae83-f528b6ed194d

The id of the target account

header Parameters
Content-Type
required
string (JSON API)
Value: "application/vnd.api+json"

The original media type of the resource.

Accept
required
string (JSON API)
Value: "application/vnd.api+json"

Content type (expressed as MIME types) the client is able to understand.

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    ]
}