M2A Mediapackage (v1)

Download OpenAPI specification:Download

M2A Mediapackage

M2A Mediapackage is a service that orchestrates the lifecycles of AWS Elemental MediaPackage (EMP) channels and endpoints through entities called packagers.

packagers

packagers are single units which hold information about how an EMP channel and endpoint(s) should be created. Created packagers start in the INITIAL state, and can be moved into STARTING or STOPPING via the packager-actions endpoint.

As packagers move through their lifecycle EMP channels and endpoints will be created and destroyed as needed. Clients can be notified of changes to the state of the packager via callbacks and information from EMP, such as origin endpoints, are surfaced on the packager.

The configuration of packagers can be managed with packager-templates.

packager-actions

packager-actions provide the mechanism by which a client can change the state of a packager. The state of the packager informs the client about the existence (or non-existence) of underlying EMP resources.

packager-templates

packager-templates are resources, exposed via the /templates endpoints, which allow a client of M2A Mediapackage to create and manage the configuration for none or more M2A Mediapackage packagers in a flexible, generic way.

Each packager-template should contain the information to configure the respective underlying EMP resource, as defined in the boto3 spec, keyed agaisnt the respective name in the packager-templates mediapackage attribute.

When a client creates a packager, they can reference a previously created packager-template via the packager-templates name, and pass configuration to it as advertised in the packager-templates mediapackage config. When it comes time to create or manage an EMP resource, the template will be rendered with the data from the packager and the final rendered template used to configure EMP.

packagers

Creates a packager resource for a given target account

The packager is created in its initial state and this does not actually provision the MediaPackage resources in the target account until a later 'start' action is submitted. On successful creation, returns a 201 and the representation of the packager in the exact same way as the corresponding GET endpoint below would. Only users with the 'write' permission for 'packager' typed resources are permitted to call this endpoint.

Request Body schema: application/json
One of
configuration
required
string (Configuration of the packager resource.)

Deprecated method for providing configuration required for the creation of origin endpoints for the underlying MediaPackage channel.

Passing configuration in this way is the same as using the template configuration option but with no config values.

eg this:

    {
      ...
      "configuration": "MY_CONFIG_NAME",
      ...
    }

is functionally equivalent to this:

    {
      ...
      "configuration": {
        "template" : "MY_CONFIG_NAME",
        "config" : []
      ...
    }

Use of the latter is preferred, even where no values need to be provided to the configuration at packager START time.

Support for this will stop as of v2 of this API.

internal-callback-url
string <uri> (State transition internal webhook url)

State transition internal webhook url is called when a packager is created and when a packagers state changes. Only 'hhtp' and 'https' URLs are allowed without in-URL authentication credentials. Webhook URLs shouldn’t contain long-lived, sensitive data. Request to the webhook url would include 'User-Agent' header with value 'm2a-mediapackage/v1'. Request body would include packager's id and packager's new state. IAM role based access policies are to sign the request, so only urls for internal M2A apis can be used. The order in which state transitions are sent cannot be guaranteed.

required
object (MetadataBase)
region
string (AWS Region Identifier for Packager Execution) ^[a-z0-9-]+$

Identifier for the region within which the packager and its resources should be executed. This region must be one in which live workflows have been enabled for your organisation.

state-callback-url
string <uri> (State transition webhook url)

State transition webhook url is called when packager is created and when packager's state is updated. Only 'hhtp' and 'https' URLs are allowed without in-URL authentication credentials. Webhook URLs shouldn’t contain long-lived, sensitive data. Request to the webhook url would include 'User-Agent' header with value 'm2a-mediapackage/v1'. Request body would include packager's id and packager's new state. To validate that the request comes from M2A, it is encouraged to use OTPs or other time-limited identifiers or credentials. To avoid blocking requests to the webhook url, 10 seconds connection and 10 seconds read timeouts are used. No retries are made. Attempt to preserve the order transition will be made but there are no guarantees.

target-account-id
required
string <uuid> (Resource identifier)

Unique identifier used for identification of individual resources in M2A Mediapackage APIs.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "target-account-id": "04a490e5-0f84-41d5-8cee-ace0ba7bfb85",
  • "configuration": {
    },
  • "region": "eu-east-1",
  • "state-callback-url": "https://www.some.url/",
  • "internal-callback-url": "https://www.some.internal.url/"
}

Response samples

Content type
application/json
{
  • "id": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
  • "target-account-id": "04a490e5-0f84-41d5-8cee-ace0ba7bfb85",
  • "metadata": {
    },
  • "configuration": {
    },
  • "state": "INITIAL",
  • "region": "eu-east-1",
  • "state-callback-url": "https://www.some.url/",
  • "internal-callback-url": "https://www.some.internal.url/"
}

Retrieve a packager by its ID.

Returns the state of the packager, its ID, target account ID and metadata which includes organisation ID, labels, date and time when the packager resource was created and the date and time when it was updated. Returns 200 on successful retrieval. If in a running/stopping state, returns summary technical details of the underlying MediaPackage channel, including its ARN, ID plus the ARNs URLs, IDs of any origin endpoints. Only user with the 'read' permission for 'packager' typed resources are permitted to call this endpoint. And only for packager resources which meet all conditions on that permission.

path Parameters
packager-id
required
string <uuid> (Resource identifier)
Example: 46106fd4-f16f-4f0f-a8a0-9c34e78b9ada

The ID of the packager.

Responses

Response samples

Content type
application/json
{
  • "id": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
  • "target-account-id": "04a490e5-0f84-41d5-8cee-ace0ba7bfb85",
  • "metadata": {
    },
  • "configuration": {
    },
  • "state": "INITIAL",
  • "region": "eu-east-1",
  • "state-callback-url": "https://www.some.url/",
  • "internal-callback-url": "https://www.some.internal.url/"
}

Update a packager.

Update a given packager.

Packagers can only be updated if they are in one of the following state:

  • INITIAL
  • FAILED
  • STOPPED
path Parameters
packager-id
required
string <uuid> (Resource identifier)
Example: 46106fd4-f16f-4f0f-a8a0-9c34e78b9ada

The ID of the packager.

Request Body schema: application/json
object (Configuration of the packager resource)

Configuration required for creating origin endpoints for the underlying MediaPackage channel

internal-callback-url
string <uri> (State transition internal webhook url)

State transition internal webhook url is called when a packager is created and when a packagers state changes. Only 'hhtp' and 'https' URLs are allowed without in-URL authentication credentials. Webhook URLs shouldn’t contain long-lived, sensitive data. Request to the webhook url would include 'User-Agent' header with value 'm2a-mediapackage/v1'. Request body would include packager's id and packager's new state. IAM role based access policies are to sign the request, so only urls for internal M2A apis can be used. The order in which state transitions are sent cannot be guaranteed.

object (MetadataLabels)
region
string (AWS Region Identifier for Packager Execution) ^[a-z0-9-]+$

Identifier for the region within which the packager and its resources should be executed. This region must be one in which live workflows have been enabled for your organisation.

state-callback-url
string <uri> (State transition webhook url)

State transition webhook url is called when packager is created and when packager's state is updated. Only 'hhtp' and 'https' URLs are allowed without in-URL authentication credentials. Webhook URLs shouldn’t contain long-lived, sensitive data. Request to the webhook url would include 'User-Agent' header with value 'm2a-mediapackage/v1'. Request body would include packager's id and packager's new state. To validate that the request comes from M2A, it is encouraged to use OTPs or other time-limited identifiers or credentials. To avoid blocking requests to the webhook url, 10 seconds connection and 10 seconds read timeouts are used. No retries are made. Attempt to preserve the order transition will be made but there are no guarantees.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "configuration": {
    },
  • "region": "eu-east-1",
  • "state-callback-url": "https://www.some.url/",
  • "internal-callback-url": "https://www.some.internal.url/"
}

Response samples

Content type
application/json
{
  • "id": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
  • "target-account-id": "04a490e5-0f84-41d5-8cee-ace0ba7bfb85",
  • "metadata": {
    },
  • "configuration": {
    },
  • "state": "INITIAL",
  • "region": "eu-east-1",
  • "state-callback-url": "https://www.some.url/",
  • "internal-callback-url": "https://www.some.internal.url/"
}

packager-actions

Starts or stop the packager.

Which action to apply must be included in the request payload. The request is only accepted if the packager is in a suitable state. E.g. a user can only 'start' a packager in its INITIAL state and similarly only 'stop' a packager in its RUNNING state. Noting that STOPPED and FAILED are both terminal states. Returns 409 if the packager is not in a suitable state to apply the action. If the action is accepted, the corresponding orchestration workflow is invoked - creating or destroying a MediaPackage channel in the process. Only users with the 'write' permission for 'packager' typed resources are permitted to call this endpoint.

path Parameters
packager-id
required
string <uuid> (Resource identifier)
Example: 46106fd4-f16f-4f0f-a8a0-9c34e78b9ada

The ID of the packager.

Request Body schema: application/json

Action to create

action
required
string
Enum: "START" "STOP"

Responses

Request samples

Content type
application/json
{
  • "action": "START"
}

Response samples

Content type
application/json
{
  • "action": "START",
  • "packager": {
    }
}

templates

Get packager templates.

JSON:API compliant endpoint for getting packager templates.

Templates can be queried by their resource_name by passing it in as a filter. Otherwise no other filtering is supported, except for by owner (target-account).

Where multiple templates are found that meet a search criteria, but not all are returned, a link will be provided to the next batch of templates. To query for all templates using these next link, continue to request them until the response either contains no next link or the API returns a 404.

By default the templates endpoint will only return ACTIVE templates. To get DELETED templates, request them using the state filter.

query Parameters
filter[template][owner]
required
string <uuid> (Resource identifier)
Example: filter[template][owner]=46106fd4-f16f-4f0f-a8a0-9c34e78b9ada

Filter which resources to return by their owning account. Only a single owning account can be queried per request.

filter[template][resource_name]
string
Example: filter[template][resource_name]=WSC PAL

Filter which resources to return by their name. Only a single name can be queried per request.

filter[template][state]
string
Enum: "ACTIVE" "DELETED"
Example: filter[template][state]=DELETED

Filter which templates to get: ACTIVE; DELETED; or both. Defaults to ACTIVE.

filter[template]
string
Example: filter[template]=resource_name, description

Return only a subset of the templates data attributes. Attributes is a comma delimited list of strings. Valid fields are:

  • description
  • mediapackage
  • metadata,
  • resource_name
  • state
page[cursor]
string <uuid> (Resource identifier)
Example: page[cursor]=46106fd4-f16f-4f0f-a8a0-9c34e78b9ada

Cursor where the operation stopped, inclusive of the previous result set. Use this value when making requests for subsequent pages.

page[size]
integer [ 1 .. 10 ]
Example: page[size]=5

The desired size of the data response. If there are fewer then the requested number of items, all items will be returned, as well as a cursor to be used for fetching the remaining items. Defaults to 10.

Responses

Response samples

Content type
application/vnd.api+json
{}

Create a packager template.

JSON:API compliant endpoint for the creation of packager-templates.

packager-templates must be uniquely named within the scope of the owning target-account. packager-templates which make use of configuration in their mediapackage resource blocks must describe that configuration in the mediapackage config.

Example:

...
  "channel": {
    "Tags": {
      "event-name": "{{config:event-name}}"
    }
  },
  "config": [
    {
      "name": "event-name",
      "description": "The human readable name of the event."
      "type": "string"
    }
  ]
...

When resources are created, m2a may include some of our own information in the rendered template, this is to ensure the validity and consistency of certain fields.

In addition, certain fields provided in the templates may be overriden or ignored entirely.

Finally, m2a makes certain information available to the packager-template designer in the form of macros. These macros can be used in a template without the need for config blocks.

Below is a complete list of the available macros, as well a description of their value when rendered

macro description example
m2a:reference_id The name of the template. Live Event 1
m2a:cloud_env The name of the m2a environment. prod
m2a:organisation_id ID of the resource (packager) owner. 00000000-0000-0000-0000-00000000000a
m2a:resource_id ID of the resource (packager) using the template. 00000000-1111-0000-0000-00000000000a
m2a:aws_account_id 12 digit AWS account number in which AWS MediaPackage resources will be created. 123456789012
query Parameters
filter[template]
string
Example: filter[template]=resource_name, description

Return only a subset of the templates data attributes. Attributes is a comma delimited list of strings. Valid fields are:

  • description
  • mediapackage
  • metadata,
  • resource_name
  • state
Request Body schema: application/vnd.api+json

A packager-template.

required
object

Responses

Request samples

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

Response samples

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

Get a packager template.

JSON:API compliant endpoint for getting a packager template by its id.

path Parameters
template-id
required
string <uuid> (Resource identifier)
Example: 46106fd4-f16f-4f0f-a8a0-9c34e78b9ada

The ID of the packager template.

query Parameters
filter[template]
string
Example: filter[template]=resource_name, description

Return only a subset of the templates data attributes. Attributes is a comma delimited list of strings. Valid fields are:

  • description
  • mediapackage
  • metadata,
  • resource_name
  • state

Responses

Response samples

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

Delete a packager template.

JSON:API compliant endpoint for deleting a packager template by its id.

Deleting a packager-template does not fully remove it from the system, but will free up its name to be used elsewhere. Deleted packagers can still be accessed directly via their ID, and requests to the templates endpoint for a collection of packager-templates will return them if a filter is set to return templates with a state of DELETED.

path Parameters
template-id
required
string <uuid> (Resource identifier)
Example: 46106fd4-f16f-4f0f-a8a0-9c34e78b9ada

The ID of the packager template.

query Parameters
filter[template]
string
Example: filter[template]=resource_name, description

Return only a subset of the templates data attributes. Attributes is a comma delimited list of strings. Valid fields are:

  • description
  • mediapackage
  • metadata,
  • resource_name
  • state

Responses

Response samples

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

Update a packager template.

JSON:API compliant endpoint for update a packager template by its id.

When updating a packager-template, the top level data attributes are treated as atomic, and any top level attribute not included in the request will be left unchanged.

path Parameters
template-id
required
string <uuid> (Resource identifier)
Example: 46106fd4-f16f-4f0f-a8a0-9c34e78b9ada

The ID of the packager template.

query Parameters
filter[template]
string
Example: filter[template]=resource_name, description

Return only a subset of the templates data attributes. Attributes is a comma delimited list of strings. Valid fields are:

  • description
  • mediapackage
  • metadata,
  • resource_name
  • state
Request Body schema: application/vnd.api+json

A packager-template update payload.

required
object

Responses

Request samples

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

Response samples

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