Live Publications

Publications represent some content at a given Destination. In the case of Live Publications, this is a live stream in the past, present, or future.

Live publications contain metadata information, which can be replicated on the desired Destination, as well as the stream information which can be consumed by an external service to stream to. They also contain some basic state information.

Live Publication Object

A Live Publication is defined as the following structure:

{
    "id": "16e4d793-0484-4923-a4d8-3e3a0604d725",
    "target": 0,
    "destinationId": "8b8d0b78-60f0-4257-b2e7-13874ecd28f6",
    "destinationName": "Example Destination",
    "transactionId": "bfe6e52b-a5c5-47f6-b77d-be0d80ff46cf",
    "contentId": "my-content-id",
    "dateCreated": "2018-10-05T12:28:14Z",
    "dateCompleted": "",
    "dateStarted": "2018-10-05T12:29:39Z",
    "publicationState": 3,
    "publicationStateString": "Completed",
    "details": {},
    "callbacks": [
        {
            "id": "4bf271e2-1544-4343-ad43-15b6d6d2cdd8",
            "publicationId": "16e4d793-0484-4923-a4d8-3e3a0604d725",
            "url": "...",
            "lastTriggered": "2018-10-05T12:29:40Z"
        }
    ]
}

The details property differs per Target and is here.

The property callbackUrls inside of details will always be a string array of the URL properties from the callbacks property from the Publication itself.

VOD Publications match Live Publications in structure, except for the details property. This means you can work with both generically.

Live Publication States

A Live Publication can go through the following states:

  • 1 = Scheduled - the Publication exists in the API but not on the Destination.
  • 2 = InProgress - the Publication is currently started but not yet complete.
  • 3 = Completed - the Publication has been completed successfully.
  • 4 = FailedDestination - the Publication’s Destination is not active.
  • 6 = FailedPublication - the Publication is lacking ingestionDetails or isUnavailable is true.

Supported Actions

Almost all Live Publication actions require both the Id of the Publication and the Id of the Destination in order to properly identify the Publication for the action.

GET /livepublications/

Get multiple Live Publications and refine by other parameters.

Query Parameters:

    targetFilter: {string} - Optional. Specify the Target (i.e. 'Facebook') to filter to.

    contentIdFilter: {string} - Optional. Specify a value to filter the ContentId to include (i.e. any publication with a content ID including the specified string).

    queryTarget: {bool} - Optional. Should the Target be queried for the additional details?

    noCache: {bool} - Optional. Set to true to bypass any existing cache.

    orderBy: {PublicationDateField} - Optional. Set to the Date field you wish to order by (Created, Started, Completed)

    from: {string} - Optional. Set to the ISO8601 DateTime string to search From.

    to: {string} - Optional. Set to the ISO8601 DateTime string to search To.

    pageNumber: {int} - Optional. Set to the Page Number to search by.

    pageSize: {int} - Optional. Set to the Page Size to search by.

Response: 200 OK and a paginated set of Publications.

GET /livepublications/transactionId/{transactionId}

Get multiple Live Publications by TransactionId and refine by other parameters.

Query Parameters:

    transactionId: {GUID} - Required. Required to identify the publication(s).

    targetFilter: {string} - Optional. Specify the Target (i.e. 'Facebook') to filter to.

    queryTarget: {bool} - Optional. Should the Target be queried for the additional details?

    noCache: {bool} - Optional. Set to true to bypass any existing cache.

Response: 200 OK and an array of Publications.

GET /livepublications/contentId/

Get a single publication by ContentId and DestinationId and refine by other parameters.

Query Parameters:

    contentId: {string} - Required to identify the publication.

    destinationId: {GUID} - Required to identify the publication.

    queryTarget: {bool} - Optional. Should the Target be queried for the additional details?

    noCache: {bool} - Optional. Set to true to bypass any existing cache.

Response: 200 OK and a Publication.

GET /livepublications/{id}

Get a single publication by Id and DestinationId.

Query Parameters:

    destinationId: {GUID} - Required to identify the publication.

    queryTarget: {bool} - Optional. Should the Target be queried for the additional details?

    noCache: {bool} - Optional. Set to true to bypass any existing cache.

Response: 200 OK and a Publication.

GET /livepublications/stats/{id}

Get the viewing statistics for a single publication.

Query Parameters:

    noCache: {bool} - Optional. Set to true to bypass any existing cache.

Response: 200 OK and the relevant JSON from below:

Facebook:

{
    "target": 0,
    "details": {
        "liveViewsMax": 0,
        "liveViews": 0,
        "likeCount": 0,
        "loveCount": 0,
        "hahaCount": 0,
        "wowCount": 0,
        "sadCount": 0,
        "angryCount": 0
    }
}

YouTube:

{
    "target": 2,
    "details": {
        "concurrentViewers": 0,
        "viewCount": 0,
        "likeCount": 0,
        "dislikeCount": 0,
        "favouriteCount": 0,
        "commentCount": 0
    }
}

POST /livepublications/

Create multiple Live Publications, using the specified Destination & PublicationJson.

Request Body:

{
    "publications": [
        {
            "contentId": "example-contentId",
            "destinationId": "72e196a4-e3a3-4ad6-b15c-2c04f9ee3d9c",
            "publicationJson": "{...}"
        }
    ]
}

It is important to ensure that the JSON format is correct for the Destination Target - visible here.

All publications that get created in the same request will have the same transactionId value.

Response: 200 OK and the JSON containing the Publication

PUT /livepublications/{id}

Update a Live Publication.

Request Body:

{
    "destinationId": "8b8d0b78-60f0-4257-b2e7-13874ecd28f6",
    "publicationJson": "{...}"
}

See PublicationJson for details on what can be submitted. It is important to ensure that the JSON format is correct for the Destination Target.

Response: 200 OK and the JSON containing the Publication

PUT /livepublications/recreate/

Recreate a single publication by Id and DestinationId.

Recreate is the process of re-setting a Publication and acquiring fresh streaming URLs. Useful in the case of unexpected errors without having to re-submit the metadata.

Response: 200 OK and the Publication.

PUT /livepublications/start/

Start a single publication by Id and DestinationId.

Support varies by Target type. However, the system will always record this action as the DateStarted time.

Response: 200 OK and an operation response:

{
    "description": "The Publication has been unpublished.",
    "isSuccessful": true
}

PUT /livepublications/stop/

Stop a single publication by Id and DestinationId.

Support varies by Target type. However, the system will always record this action as the DateCompleted time.

Response: 200 OK and an operation response:

{
    "description": "The Publication has been unpublished.",
    "isSuccessful": true
}

PUT /livepublications/publish/

Publish a single publication by Id and DestinationId.

Support varies by Target type.

Response: 200 OK and an operation response:

{
    "description": "The Publication has been published.",
    "isSuccessful": true
}

PUT /livepublications/unpublish/

Unpublish a single publication by Id and DestinationId.

Support varies by Target type.

Response: 200 OK and an operation response:

{
    "description": "The Publication has been unpublished.",
    "isSuccessful": true
}

DEL /livepublications/{id}

Delete a single publication by Id and DestinationId.

Response: 200 OK

DEL /livepublications/all/{contentId}

Delete multiple Live Publications by ContentId.

Response: 200 OK

DEL /livepublications/cache/

Delete all Live Publication cache.

Response: 200 OK