Download OpenAPI specification:Download
M2A Mediapackage is a service that orchestrates the lifecycles of AWS Elemental MediaPackage (EMP) channels and endpoints through entities called 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 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 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.
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.
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:
is functionally equivalent to this:
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. |
{- "metadata": {
- "organisation": "2cea7980-72f3-4e50-8590-28fb009390c9",
- "labels": [
- {
- "key": "m2amedia.tv:name",
- "value": "AWS MediaPackage packager (46106fd4-f16f-4f0f-a8a0-9c34e78b9ada)"
}
]
}, - "target-account-id": "04a490e5-0f84-41d5-8cee-ace0ba7bfb85",
- "configuration": {
- "template": "My Awesome Template",
- "config": [
- {
- "name": "event-id",
- "value": "event123"
}, - {
- "name": "day",
- "value": "Friday"
}
]
}, - "region": "eu-east-1",
}
{- "id": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
- "target-account-id": "04a490e5-0f84-41d5-8cee-ace0ba7bfb85",
- "metadata": {
- "organisation": "2cea7980-72f3-4e50-8590-28fb009390c9",
- "labels": [
- {
- "key": "m2amedia.tv:name",
- "value": "AWS MediaPackage packager (46106fd4-f16f-4f0f-a8a0-9c34e78b9ada)"
}
], - "created-date": "2022-02-04T12:34:37.805624",
- "updated-date": "2022-02-04T12:34:37.805624"
}, - "configuration": {
- "template": "My Awesome Template",
- "config": [
- {
- "name": "event-id",
- "value": "event123"
}, - {
- "name": "day",
- "value": "Friday"
}
]
}, - "state": "INITIAL",
- "region": "eu-east-1",
}
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.
packager-id required | string <uuid> (Resource identifier) Example: 46106fd4-f16f-4f0f-a8a0-9c34e78b9ada The ID of the packager. |
{- "id": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
- "target-account-id": "04a490e5-0f84-41d5-8cee-ace0ba7bfb85",
- "metadata": {
- "organisation": "2cea7980-72f3-4e50-8590-28fb009390c9",
- "labels": [
- {
- "key": "m2amedia.tv:name",
- "value": "AWS MediaPackage packager (46106fd4-f16f-4f0f-a8a0-9c34e78b9ada)"
}
], - "created-date": "2022-02-04T12:34:37.805624",
- "updated-date": "2022-02-04T12:34:37.805624"
}, - "configuration": {
- "template": "My Awesome Template",
- "config": [
- {
- "name": "event-id",
- "value": "event123"
}, - {
- "name": "day",
- "value": "Friday"
}
]
}, - "state": "INITIAL",
- "region": "eu-east-1",
}
Update a given packager.
Packagers can only be updated if they are in one of the following state:
packager-id required | string <uuid> (Resource identifier) Example: 46106fd4-f16f-4f0f-a8a0-9c34e78b9ada The ID of the packager. |
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. |
{- "metadata": {
- "labels": [
- {
- "key": "m2amedia.tv:name",
- "value": "AWS MediaPackage packager (46106fd4-f16f-4f0f-a8a0-9c34e78b9ada)"
}
]
}, - "configuration": {
- "template": "My Awesome Template",
- "config": [
- {
- "name": "event-id",
- "value": "event123"
}, - {
- "name": "day",
- "value": "Friday"
}
]
}, - "region": "eu-east-1",
}
{- "id": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
- "target-account-id": "04a490e5-0f84-41d5-8cee-ace0ba7bfb85",
- "metadata": {
- "organisation": "2cea7980-72f3-4e50-8590-28fb009390c9",
- "labels": [
- {
- "key": "m2amedia.tv:name",
- "value": "AWS MediaPackage packager (46106fd4-f16f-4f0f-a8a0-9c34e78b9ada)"
}
], - "created-date": "2022-02-04T12:34:37.805624",
- "updated-date": "2022-02-04T12:34:37.805624"
}, - "configuration": {
- "template": "My Awesome Template",
- "config": [
- {
- "name": "event-id",
- "value": "event123"
}, - {
- "name": "day",
- "value": "Friday"
}
]
}, - "state": "INITIAL",
- "region": "eu-east-1",
}
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.
packager-id required | string <uuid> (Resource identifier) Example: 46106fd4-f16f-4f0f-a8a0-9c34e78b9ada The ID of the packager. |
Action to create
action required | string Enum: "START" "STOP" |
{- "action": "START"
}
{- "action": "START",
- "packager": {
- "id": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
- "state": "STARTING"
}
}
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.
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:
|
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. |
{- "meta": {
- "totalPages": 4,
- "totalRecords": 32
}, - "links": {
}, - "data": [
- {
- "data": {
- "type": "packager-template",
- "id": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
- "attributes": {
- "description": "My awesome HLS packager template!",
- "medipackage": {
- "channel": { },
- "logging": { },
- "endpoints": [
- { }
], - "config": [
- {
- "name": "bitrate-1",
- "type": "integer",
- "description": "The highest bitrate for this template."
}
]
}, - "metadata": {
- "organisation": "2cea7980-72f3-4e50-8590-28fb009390c9",
- "labels": [
- {
- "key": "m2amedia.tv:name",
- "value": "AWS MediaPackage packager template (46106fd4-f16f-4f0f-a8a0-9c34e78b9ada)"
}
], - "created": "2022-02-04T12:34:37.805624",
- "updated": "2022-02-04T12:34:37.805624",
- "last-modified-by": "ac803e4f-bf04-4122-9ed2-55b7f6d34f77"
}, - "resource_name": "HLS High Bitrate",
- "state": "DELETED"
}, - "relationships": {
- "owner": {
- "data": {
- "id": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
- "type": "target-account"
}
}
}
}
}
]
}
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 |
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:
|
A packager-template.
required | object |
{- "data": {
- "type": "packager-template",
- "attributes": {
- "description": "My awesome HLS packager template!",
- "medipackage": {
- "channel": { },
- "logging": { },
- "endpoints": [
- { }
], - "config": [
- {
- "name": "bitrate-1",
- "type": "integer",
- "description": "The highest bitrate for this template."
}
]
}, - "metadata": {
- "organisation": "2cea7980-72f3-4e50-8590-28fb009390c9",
- "labels": [
- {
- "key": "m2amedia.tv:name",
- "value": "AWS MediaPackage packager (46106fd4-f16f-4f0f-a8a0-9c34e78b9ada)"
}
]
}, - "resource_name": "HLS High Bitrate"
}, - "relationships": {
- "owner": {
- "data": {
- "id": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
- "type": "target-account"
}
}
}
}
}
{- "data": {
- "type": "packager-template",
- "id": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
- "attributes": {
- "description": "My awesome HLS packager template!",
- "medipackage": {
- "channel": { },
- "logging": { },
- "endpoints": [
- { }
], - "config": [
- {
- "name": "bitrate-1",
- "type": "integer",
- "description": "The highest bitrate for this template."
}
]
}, - "metadata": {
- "organisation": "2cea7980-72f3-4e50-8590-28fb009390c9",
- "labels": [
- {
- "key": "m2amedia.tv:name",
- "value": "AWS MediaPackage packager template (46106fd4-f16f-4f0f-a8a0-9c34e78b9ada)"
}
], - "created": "2022-02-04T12:34:37.805624",
- "updated": "2022-02-04T12:34:37.805624",
- "last-modified-by": "ac803e4f-bf04-4122-9ed2-55b7f6d34f77"
}, - "resource_name": "HLS High Bitrate",
- "state": "DELETED"
}, - "relationships": {
- "owner": {
- "data": {
- "id": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
- "type": "target-account"
}
}
}
}
}
JSON:API compliant endpoint for getting a packager template by its id.
template-id required | string <uuid> (Resource identifier) Example: 46106fd4-f16f-4f0f-a8a0-9c34e78b9ada The ID of the packager template. |
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:
|
{- "data": {
- "type": "packager-template",
- "id": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
- "attributes": {
- "description": "My awesome HLS packager template!",
- "medipackage": {
- "channel": { },
- "logging": { },
- "endpoints": [
- { }
], - "config": [
- {
- "name": "bitrate-1",
- "type": "integer",
- "description": "The highest bitrate for this template."
}
]
}, - "metadata": {
- "organisation": "2cea7980-72f3-4e50-8590-28fb009390c9",
- "labels": [
- {
- "key": "m2amedia.tv:name",
- "value": "AWS MediaPackage packager template (46106fd4-f16f-4f0f-a8a0-9c34e78b9ada)"
}
], - "created": "2022-02-04T12:34:37.805624",
- "updated": "2022-02-04T12:34:37.805624",
- "last-modified-by": "ac803e4f-bf04-4122-9ed2-55b7f6d34f77"
}, - "resource_name": "HLS High Bitrate",
- "state": "DELETED"
}, - "relationships": {
- "owner": {
- "data": {
- "id": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
- "type": "target-account"
}
}
}
}
}
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.
template-id required | string <uuid> (Resource identifier) Example: 46106fd4-f16f-4f0f-a8a0-9c34e78b9ada The ID of the packager template. |
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:
|
{- "data": {
- "type": "packager-template",
- "id": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
- "attributes": {
- "description": "My awesome HLS packager template!",
- "medipackage": {
- "channel": { },
- "logging": { },
- "endpoints": [
- { }
], - "config": [
- {
- "name": "bitrate-1",
- "type": "integer",
- "description": "The highest bitrate for this template."
}
]
}, - "metadata": {
- "organisation": "2cea7980-72f3-4e50-8590-28fb009390c9",
- "labels": [
- {
- "key": "m2amedia.tv:name",
- "value": "AWS MediaPackage packager template (46106fd4-f16f-4f0f-a8a0-9c34e78b9ada)"
}
], - "created": "2022-02-04T12:34:37.805624",
- "updated": "2022-02-04T12:34:37.805624",
- "last-modified-by": "ac803e4f-bf04-4122-9ed2-55b7f6d34f77"
}, - "resource_name": "HLS High Bitrate",
- "state": "DELETED"
}, - "relationships": {
- "owner": {
- "data": {
- "id": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
- "type": "target-account"
}
}
}
}
}
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.
template-id required | string <uuid> (Resource identifier) Example: 46106fd4-f16f-4f0f-a8a0-9c34e78b9ada The ID of the packager template. |
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:
|
A packager-template update payload.
required | object |
{- "data": {
- "type": "packager-template",
- "attributes": {
- "description": "My awesome HLS packager template!",
- "medipackage": {
- "channel": { },
- "logging": { },
- "endpoints": [
- { }
], - "config": [
- {
- "name": "bitrate-1",
- "type": "integer",
- "description": "The highest bitrate for this template."
}
]
}, - "metadata": {
- "labels": [
- {
- "key": "event-tier",
- "value": "5"
}
]
}, - "resource_name": "HLS High Bitrate"
}
}
}
{- "data": {
- "type": "packager-template",
- "id": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
- "attributes": {
- "description": "My awesome HLS packager template!",
- "medipackage": {
- "channel": { },
- "logging": { },
- "endpoints": [
- { }
], - "config": [
- {
- "name": "bitrate-1",
- "type": "integer",
- "description": "The highest bitrate for this template."
}
]
}, - "metadata": {
- "organisation": "2cea7980-72f3-4e50-8590-28fb009390c9",
- "labels": [
- {
- "key": "m2amedia.tv:name",
- "value": "AWS MediaPackage packager template (46106fd4-f16f-4f0f-a8a0-9c34e78b9ada)"
}
], - "created": "2022-02-04T12:34:37.805624",
- "updated": "2022-02-04T12:34:37.805624",
- "last-modified-by": "ac803e4f-bf04-4122-9ed2-55b7f6d34f77"
}, - "resource_name": "HLS High Bitrate",
- "state": "DELETED"
}, - "relationships": {
- "owner": {
- "data": {
- "id": "46106fd4-f16f-4f0f-a8a0-9c34e78b9ada",
- "type": "target-account"
}
}
}
}
}