Media Syndication Integration

The VIS consumes the MediaSyndication API to facilitate syndication via the Event concept.

The MediaSyndication API does not have the Event concept itself, so unless you are writing a specific integration you want to refer to this page for supported actions, but supplement this with knowledge from the MediaSyndication API documentation.

Important:

Before going any further, you must understand the MediaSyndication concepts of Destinations and Publications. You should be aware of enumerated values such as Targets.

In general, the VIS integration restructures the information from the MediaSyndication API, and uses the Event information to automatically set certain fields.

Media Destinations

Destinations represent the access to the Target APIs, and are essentially quite similar to ‘Channels’.

See here for information on activation - a key concept.

Media Destination Object 

{
  "id": "9cbd95c0-7c6d-4613-945c-ef82169bee27",
  "name": "Destination",
  "target": 4,
  "configJson": "{...}",
  "active": true
}

Supported Actions

POST /media/destination/

Add a Destination.

Request Body:

{
    "name": "Destination",
    "target": "Facebook",
    "destinationJson": "{...}",
    "active": true
}

Note: it is not recommended to specify Active as this is controlled by the internal workflow. However, if needed you can ‘reset’ it a Destination by passing False.

Note: target does not have to be the enumerated value, and can be a text representation such as “Facebook”.

Response: 200 OK and JSON containing a Media Destination object.

PUT /media/destination/{id}

Updates a given Destination.

This request behaves the same as the Add Destination.

PUT /media/destination/active/{id}

Updates only the active property on the Destination.

Query Parameters:

Name Type Required Description
active bool Yes The new value for the Active property.

Note: this should only be used to repair or reset a Destination’s activation workflow.

Response: 200 OK

PUT /media/destination/activate/{id}

Calls the Media API to check the activation process against the Destination.

Response: 200 OK and JSON matching the below.

{
    "actionTitle": "Destination requires ...",
    "actionDescription": "Please activate by ...",
    "actionRequired": true
}

GET /media/destination/

Get multiple Destinations.

Query Parameters:

Name Type Required Description
targetFilter String No set to a particular Target type to filter on, e.g. ‘Facebook’.
onlyActive bool No Whether or not to filter to only active Destinations.
noCache bool No Whether or not to bypass cache. Defaults to False.

Response: 200 OK and a JSON array containing multiple Media Destination objects.

GET media/destination/{id}

Get a specific Destination by Id.

Response: 200 OK and JSON containing a Media Destination object.

DEL /media/destination/{id}

Deletes the Destination and all child publications from the MediaSyndication service.

Response: 200 OK

Media Destination Properties

A Destination can have custom properties, which are used to represent extra data not relevant to the Target integration.

Media Destination Property Object 

{
  "id": "72859091-6ddb-459a-9803-c85f26919589",
  "category": "category-here",
  "key": "key-here",
  "value": "value-here",
  "client": "vualto-example",
  "destinationId": "c00d0849-0bf2-4583-ab13-5a7defd9938f"
}

Supported Actions

POST /media/destinationproperty/

Adds a new property, or updates an existing one if an Id is provided. Duplicate Category & Key values cause an update too.

Request Body:

{
    "id": "c00d0849-0bf2-4583-ab13-5a7defd9938f",
    "destinationId": "1b0d7fa1-bfcf-4b46-b422-37528346d90d",
    "category": "category-here",
    "key": "key-here",
    "value": "value-here"
}

Note: id is optional.

Response: 200 OK

GET /media/destinationproperty/all/{destinationId}

Gets all properties for a Destination.

Query Parameters:

Name Type Required Description
category String No The Category value to filter to.
key String No The Key value to filter to.
value String No The Value value to filter to.

Response: 200 OK and a JSON array containing multiple Media Destination Properties.

GET /media/destinationproperty/id/{id}

Gets a specific property based on its ID.

Response: 200 OK and JSON containing the Media Destination Properties.

GET /media/destinationproperty/{destinationId}

Fetches a single property from a Destination based on the given Category & Key values. For use when the Id is not known.

Query Parameters:

Name Type Required Description
category String Yes The Category value.
key String Yes The Key value.

Response: 200 OK and JSON containing the Media Destination Properties.

DEL /media/destinationproperty/id/{id}

Deletes a given property by Id.

Response: 200 OK

DEL /media/destinationproperty/{destinationId}

Deletes a given property by its Destination Id, Category, and Key values.

Query Parameters:

Name Type Required Description
category String Yes The Category value.
key String Yes The Key value.

Response: 200 OK

DEL /media/destinationproperty/all/{destinationId}

Deletes all properties for a Destination.

Query Parameters:

Name Type Required Description
category String No The Category value to filter to.
key String No The Key value to filter to.
value String No The Value value to filter to.

Response: 200 OK

Media Publications

Media Publication Object 

{
  "id": "1b0d7fa1-bfcf-4b46-b422-37528346d90d",
  "target": 0,
  "destinationId": "b237e4f1-14ff-4542-b342-67e275824d46",
  "contentId": "my-content-id-here",
  "dateCreated": "iso8601-datetime-here",
  "dateCompleted": "iso8601-datetime-here",
  "dateStarted": "iso8601-datetime-here",
  "details": {},
  "callbacks":
    [
        {
          "id": "2834c93b-e76e-4fef-950b-bca37191585f",
          "publicationId": "1b0d7fa1-bfcf-4b46-b422-37528346d90d",
          "url": "url-here",
          "lastTriggered": "iso8601-datetime-here"
        }
    ]
}

The details object varies depending on the Target, whether it is live or VOD, and can be null if the MediaSyndication service was not able to retrieve the information. These are not restructured by the VIS so you should refer to the MediaSyndication documentation for further information on live or VOD.

Supported Actions

LIVE

Live Publications currently rely on Wowza as a means to dynamically distribute streams. If your solution does not have this configured then you will not be able to use this functionality.

POST /media/livepublication/

Create multiple live publications.

Request Body:

{
    "eventId": "8c5b1a96-bf66-4f11-b16b-58d168ea9754",
    "publications": [
        {
            "audioInputId": "7f05d046-f667-42cd-89cc-3f992c1b6583",
            "destinationId": "7f05d046-f667-42cd-89cc-3f992c1b6583",
            "publicationJson": "{...}"
        }
    ],
    "startInstantly": false
}
  • publicationJson should be a serialised JSON object containing the relevant details for the Publication. Refer to the core Media Syndication documentation here.
  • startInstantly is a flag to immediately start these publication after they are created - this simply saves time and additional requests.

Response: 200 OK

PUT /media/livepublication/recreate/

Recreates a single live publication (i.e. re-tries creation against Target, discarding the previous details).

If the API is not returning any details you may want to try this operation.

Request Body:

{
    "eventId": "7f05d046-f667-42cd-89cc-3f992c1b6583",
    "publicationId": "974b644d-eff4-45b2-9256-0f488b063b72",
    "destinationId": "249b575d-24c1-4e75-bdee-05cf72f2eb5c",
    "removeOriginal": false
}

Note: removeOriginal is optional, but passing True is common.

Response: 200 OK

PUT /media/livepublication/start/

Start a single live publication by adding StreamTargets on Wowza and calling ‘Start’ on the MediaSyndication API.

Request Body:

{
    "eventId": "1c0ce4ce-8636-4da4-92dd-22c3845fbcef",
    "publicationId": "2c9ca563-4f7d-4e87-8aa4-89d4f3177de2",
    "destinationId": "82ba8636-d4cb-46de-a75c-bb2bc3199d99"
}

Response: 200 OK

PUT /media/livepublication/stop/

Stop a single live publication by removing the StreamTargets on Wowza and calling ‘Stop’ on the MediaSyndication API.

Request Body:

{
    "eventId": "1c0ce4ce-8636-4da4-92dd-22c3845fbcef",
    "publicationId": "2c9ca563-4f7d-4e87-8aa4-89d4f3177de2",
    "destinationId": "82ba8636-d4cb-46de-a75c-bb2bc3199d99"
}

Response: 200 OK

PUT /media/livepublication/start/all/

Start multiple publications by adding StreamTargets on Wowza and calling ‘Start’ on the MediaSyndication API (executes concurrently).

Request Body:

{
    "eventId": "82ba8636-d4cb-46de-a75c-bb2bc3199d99",
    "publications": [
        {
            "publicationId": "65fb2781-9447-490d-b950-91a2741bd331",
            "destinationId": "2c9ca563-4f7d-4e87-8aa4-89d4f3177de2"
        }
    ]
}

Note: errors occur internally here to give every Publication an attempt to start. If the Publication is not started after this action, then a fault occurred.

Response: 200 OK

PUT /media/livepublication/stop/all/

Stop multiple publications by removing StreamTargets on Wowza and calling ‘Stop’ on the Media API.

Request Body:

{
    "eventId": "82ba8636-d4cb-46de-a75c-bb2bc3199d99",
    "publications": [
        {
            "publicationId": "65fb2781-9447-490d-b950-91a2741bd331",
            "destinationId": "2c9ca563-4f7d-4e87-8aa4-89d4f3177de2"
        }
    ]
}

Note: errors occur internally here to give every Publication an attempt to stop. If the Publication is not stopped after this action, then a fault occurred.

Response: 200 OK

PUT /media/livepublication/publish/

Publish a single live publication by calling ‘Publish’ on Media API.

Request Body:

{
    "eventId": "1c0ce4ce-8636-4da4-92dd-22c3845fbcef",
    "publicationId": "2c9ca563-4f7d-4e87-8aa4-89d4f3177de2",
    "destinationId": "82ba8636-d4cb-46de-a75c-bb2bc3199d99"
}

Response: 200 OK

PUT /media/livepublication/unpublish/

Un-publish a single live publication by calling ‘Un-publish’ on Media API.

Request Body:

{
    "eventId": "1c0ce4ce-8636-4da4-92dd-22c3845fbcef",
    "publicationId": "2c9ca563-4f7d-4e87-8aa4-89d4f3177de2",
    "destinationId": "82ba8636-d4cb-46de-a75c-bb2bc3199d99"
}

Response: 200 OK

GET /media/livepublication/

Get multiple live publications, filtered by parameters.

Query Parameters:

Name Type Required Description
targetFilter String No Refine to a particular Target name (i.e. ‘Facebook’).
contentIdFilter String No Search for publications containing a particular string.
queryTarget bool No Set to True to fetch data from the Target API.
noCache bool No Whether or not to skip cache. Defaults to False.
orderBy String No “Created”, “Started”, or “Completed”.
from String No ISO8601 datetime.
to String No ISO8601 datetime.
pageNumber int No The page number.
pageSize int No The page size.

Response: 200 OK and a JSON array containing multiple Publication objects.

GET /media/livepublication/transactionId/{transactionId}

Get multiple live publications by TransactionId (i.e. those created in the same batch).

Query Parameters:

Name Type Required Description
contentIdFilter String No Search for publications containing a particular string.
queryTarget bool No Set to True to fetch data from the Target API.
noCache bool No Whether or not to skip cache. Defaults to False.

Response: 200 OK and a JSON array containing multiple Publication objects.

GET /media/livepublication/{id}

Get a live publication by its Id and DestinationId.

Query Parameters:

Name Type Required Description
destinationId String Yes Required to identify the type of Publication.
queryTarget bool No Set to True to fetch data from the Target API.
noCache bool No Whether or not to skip cache. Defaults to False.

Response: 200 OK and JSON containing Publication objects.

GET /media/livepublication/contentId/{contentId}

Gets a live publication by its ContentId and DestinationId.

Query Parameters:

Name Type Required Description
destinationId String Yes Required to identify the type of Publication.
queryTarget bool No Set to True to fetch data from the Target API.
noCache bool No Whether or not to skip cache. Defaults to False.

Response: 200 OK and JSON containing Publication objects.

GET /media/livepublication/statistics/{publicationId}

Get the statistics for a live publication by Id and DestinationId.

Query Parameters:

Name Type Required Description
destinationId String Yes Required to identify the type of Publication.

Response: 200 OK and JSON response from the MediaSyndication API.

DEL /media/livepublication/

Delete multiple publications.

Request Body:

{
    "eventId": "116e590f-79a6-46d5-818c-79a64eee886c",
    "publications": [
        {
            "publicationId": "9ab0c720-d186-45d1-86e7-b4f72df72d73",
            "destinationId": "490a8064-8c11-4004-b252-b49666673d29",
            "hardDelete": false
        }
    ]
}

Response: 200 OK

VOD

POST /media/vodpublication/

Add multiple VOD Publications. The Event should have an available MP4 for syndication, otherwise it will not work.

Request Body:

{
    "eventId": "9ab0c720-d186-45d1-86e7-b4f72df72d73",
    "publications": [
        {
            "destinationId": "490a8064-8c11-4004-b252-b49666673d29",
            "publicationJson": "{...}",
        }
    ]
}
  • publicationJson should be a serialised JSON object containing the relevant details for the Publication. Refer to the core Media Syndication documentation here.

Response: 200 OK

GET /media/vodpublication/

Get multiple VOD publications, filtered by parameters.

Query Parameters:

Name Type Required Description
targetFilter String No Refine to a particular Target name (i.e. ‘Facebook’).
contentIdFilter String No Search for publications containing a particular string.
queryTarget bool No Set to True to fetch data from the Target API.
noCache bool No Whether or not to skip cache. Defaults to False.
orderBy String No “Created”, “Started”, or “Completed”.
from String No ISO8601 datetime.
to String No ISO8601 datetime.
pageNumber int No The page number.
pageSize int No The page size.

Response: 200 OK and a JSON array containing multiple Publication objects.

GET /media/vodpublication/transactionId/{transactionId}

Get multiple VOD publications by TransactionId (i.e. those created in the same batch).

Query Parameters:

Name Type Required Description
contentIdFilter String No Search for publications containing a particular string.
queryTarget bool No Set to True to fetch data from the Target API.
noCache bool No Whether or not to skip cache. Defaults to False.

Response: 200 OK and a JSON array containing multiple Publication objects.

GET /media/vodpublication/{id}

Get a VOD publication by its Id and DestinationId.

Query Parameters:

Name Type Required Description
destinationId String Yes Required to identify the type of Publication.
queryTarget bool No Set to True to fetch data from the Target API.
noCache bool No Whether or not to skip cache. Defaults to False.

Response: 200 OK and JSON containing Publication objects.

GET /media/vodpublication/content/{contentId}

Gets a VOD publication by its ContentId and DestinationId.

Query Parameters:

Name Type Required Description
destinationId String Yes Required to identify the type of Publication.
queryTarget bool No Set to True to fetch data from the Target API.
noCache bool No Whether or not to skip cache. Defaults to False.

Response: 200 OK and JSON containing Publication objects.

DEL /media/vodpublications/{id}

Delete a VOD Publication by Id.

Query Parameters:

Name Type Required Description
hardDelete Boolean No Defaults to False. Whether or not to remove from the target platform.

Response: 200 OK