Release notes

2024r13

Corrections to historical broadcast dates in content API

In version 2024r11, historical broadcast dates were added to the content API. However, some errors needed to be corrected.

In the POST and PUT /historicalBroadcastDates calls, the channel attribute can be specified in the body. From this version, a GET /channels drop-down call has been added to retrieve the available values.

Additionally, in the

  • POST /historicalBroadcastDates;

  • PUT /historicalBroadcastDates;

  • GET /historicalBroadcastDates/{historicalBroadcastDateId};

  • GET /programs, /episodes, /products,

the announcedTime and broadcasted attributes were part of the YAML but those were not the correct attributes to update the Hour and Broadcast fields on a historical broadcast date. From this version, they were replaced in the YAML by the hour and broadcast attributes.

For example:

{
  "contentId": "9294345527",
  "date": "1993-04-14",
  "historicalBroadcastDateId": "API",
  "channel": "MGX",
  "hour": "10:00",
  "broadcast": "true",
  "freeRerun": "false",
  "realKPI1": "0.1",
  "realKPI2": "0.2",
  "realKPI3": "1"
}

Finally, the historicalBroadcastDates array was added to the YAML for the

  • POST /programs/:contentId/versions/:versionId

  • POST /episodes/:contentId/versions/:versionId
  • POST/PUT programs
  • POST/PUT episodes,

but it could not be used in these calls. Therefore, it has been removed from the YAML for these calls.

The YAML has been updated for these changes. The latest version can be retrieved by using the GET /api call.

API developers

The following has changed to the YAML:

At line 1819, the reference to the schema has changed.
At line 2587, the /channels path was added.
At line 3153, 3181, 3200, 3242, the historicalBroadcastDates property was removed.
At line 3710, several changes were made to the HistoricalBroadcastDate schema.
At line 3740, several changes were made to the HistoricalBroadcastDateForGet schema.

For easier viewing, the YAMLs can also be compared here: TextCompare

Fix for message for invalid parental rating in business API service when using content API

Previously, when

  • a regulator was configured with some allowed parental ratings, for example, All ages and 16+;

  • a product had that regulator and an allowed parent rating defined, for example, 16+;

  • that parental rating was inactivated in the Parental rating drop-down list;

  • a PUT or POST call was used to update the product with the inactivated drop-down value as parental rating, and

  • the business API service was running,

    • in the user interface, message 4168 would appear in the service launcher and the service would hang until it was closed.

    • as a Windows service, it would crash.

This issue has been fixed. In this scenario, an error message with status code 422 is also returned:

{
    "statusCode": "422",
    "message": "Operation cannot be completed due to violations",
    "timestamp": "2025-01-02T16:57:57Z",
    "concept": "Program",
    "id": "143048527",
    "errors": [
        {
            "errorCode": "CORE-00002",
            "description": "The parental rating Ages 9 and above is not available for the regulator Ofcom.",
            "data": [
                "Ages 9 and above",
                "Ofcom"
            ]
        }
    ]
}

Fix for inheritance of episodeNumber in POST and PUT /episodes call of content API

Since a previous version, the propagateToVersions parameter can be added to the URL of the POST and PUT /seasons, /programs and /episodes calls. This allows fields to be inherited by other product versions.

Previously, when

  • using the parameter in the URL of the POST and PUT /episodes call,

  • and the episodeNumber attribute was updated in the call, then

it would not be propagated to the other versions of the episode.

This issue has been fixed.

2024r12

Fix for performance when creating episodes on series with many episodes

Previously, when

  • a series with the content collection structure Standard season had a lot of episodes generated already, for example 2000;

  • and additional episodes were created, either manually or using the content API,

this could be very slow. This was because the recalculation of the internal number was checking all content collection items in an inefficient way for large numbers of episodes.

This issue has been fixed. The recalculation has been optimized so performance has been improved.

Note that it is recommended not to have series with this many episodes as it could cause other performance issues.

2024r11

Historical broadcast dates in content API

Historical broadcast dates indicate that a transmission was planned before the broadcaster started to use Mediagenix Base platform. Such historical transmissions are important for determining whether a newly planned transmission is a product rerun or not. Historical broadcast dates can be managed in the product navigator.

From this version, it is possible to create, edit and delete historical broadcast dates on products using the content API.

For this, an external reference was added to historical broadcast dates.

The following calls have been added to the content API:

GET historicalBroadcastDates/{historicalBroadcastDateId}

This call retrieves all the details of a single historical broadcast date. This means the historicalBroadcastDateId, i.e. the external reference, is a mandatory parameter in the URL.

The body of the response contains the properties of the historical broadcast day:

{
    "historicalBroadcastDateId": "9501450103",
    "contentId": "9294345527",
    "channel": null,
    "date": "2022-11-19",
    "hour": null,
    "isEffective": false,
    "freeRerun": false,
    "realKPI1": null,
    "realKPI2": null,
    "realKPI3": null
}

The isEffective attribute maps to the Broadcast property on a historical broadcast date.

POST /historicalBroadcastDates

This call allows to create or update a historical broadcast date. The contentId and date attributes are mandatory. If the call is used to update, the historicalBroadcastDateId is also mandatory in the body.

The body of the call contains the following attributes:

  • contentId: The external reference of the content for which the historical broadcast date should be created.

  • date: The date in YYYY-MM-DD format.

  • historicalBroadcastDateId: The external reference of the historical broadcast date.

  • channel: The API reference of the channel of the broadcast date.

  • hour: The hour in HH:MM or HH:MM:SS format.

  • isEffective: An indication of whether the date should be marked as broadcast (true) or not (false).

  • freeRerun: An indication of whether the date should be marked as a free rerun (true) or not (false).

  • realKPI1-3: A Key Performance Indicator associated with the broadcast date in fixed point decimal format.

An example of the body:

{
  "contentId": "9294345527",
  "date": "1993-04-14",
  "historicalBroadcastDateId": "API",
  "channel": "MGX",
  "hour": "10:00",
  "isEffective": "true",
  "freeRerun": "false",
  "realKPI1": "0.1",
  "realKPI2": "0.2",
  "realKPI3": "1"
}

Due to an error in the YAML, the POST and PUT call bodies contain announcedTime and broadcasted instead of the hour and isEffective attributes respectively. These will not update the broadcast date. If hour and isEffective are used, the Hour and Broadcast fields on a historical broadcast date can be edited. The YAML will be corrected in an upcoming version.

PUT /historicalBroadcastDates/{historicalBroadcastDateId}

This call allows to update a historical broadcast date. The contentId and date attributes are mandatory in the body of the call while the historicalBroadcastDateId is mandatory in the URL of the call.

The body has the same attributes as the POST call.

DELETE /historicalBroadcastDates/{historicalBroadcastDateId}

This call deletes a historical broadcast date. The historicalBroadcastDateId is mandatory in the URL of the call.

The following calls have been adapted:

GET /programs, /episodes, /products

In the GET /programs, /episodes and /products call, the historicalBroadcastDates array has been added to the response. It returns all historical broadcast dates on the product and its properties if the ID belongs to an episode or program.

For example:

 "historicalBroadcastDates": [
        {
            "historicalBroadcastDateId": "9501450103",
            "contentId": "9294345527",
            "channel": null,
            "date": "2022-11-19",
            "hour": null,
            "isEffective": false,
            "freeRerun": false,
            "realKPI1": null,
            "realKPI2": null,
            "realKPI3": null
        },
        {
            "historicalBroadcastDateId": "API",
            "contentId": "9294345527",
            "channel": "MGX",
            "date": "1993-04-14",
            "hour": "10:00:00",
            "isEffective": true,
            "freeRerun": false,
            "realKPI1": 0.1000,
            "realKPI2": 0.2000,
            "realKPI3": 1
        }
    ]

The YAML has been updated for these changes. The latest version can be retrieved by using the GET /api call.

API developers

The following has changed to the YAML:

At line 1732, the paths for the historical broadcast date calls have been added.
At line 3114, the historicalBroadcastDates has been added to the properties of the Program schema.
At line 3140, the historicalBroadcastDates has been added to the properties of the ProgramForGet schema.
At line 3146, the historicalBroadcastDates has been added to the properties of the ProgramVersion schema.
At line 3168, the historicalBroadcastDates has been added to the properties of the Episode schema.
At line 3202, the historicalBroadcastDates has been added to the properties of the EpisodeForGet schema.
At line 3213, the historicalBroadcastDates has been added to the properties of the EpisodeVersion schema.
At line 3684, the HistoricalBroadcastDate and HistoricalBroadcastDateForGet schemas have been added.

Note that the historicalBroadcastDates array was added to the YAML for the

  • POST /programs/:contentId/versions/:versionId

  • POST /episodes/:contentId/versions/:versionId

  • POST/PUT programs

  • POST/PUT episodes

calls but this was not intended as the attribute cannot be used there.

For easier viewing, the YAMLs can also be compared here: TextCompare

Sigma ID in GET calls of content API

In the Mediagenix Hive platform, content is identified by the sigma ID. This is also visible in Mediagenix Base platform and is used for smooth switching between the applications. (RN-5831)

Previously, the content API only showed the API reference used in the Mediagenix Base platform, but not the sigma ID. However, this could be needed for external systems that want to also perform updates in the Mediagenix Hive platform.

From this version, the sigmaId attribute has been added to the response of the GET calls in the content API:

  • GET/products/{contentId}

  • GET/programs/{contentId}

  • GET/series/{contentId}

  • GET/seasons/{contentId}

  • GET/episodes/{contentId}

  • GET/contentCollections/{contentId}

The sigma IDs of subconcepts, meaning the episodes of a season, the seasons of a series and content collection items, have not been added to the GET /seasons, /series and /contentCollections calls as that would be breaking changes for the API. Only the ID of the main concept of the call is included.

An example of the response of the GET /products call:

{
    "contentId": "143048527",
    "contentType": "program",
    "title": "AVENGERS: ENDGAME",
    "duration": "02:43:00",
    "productCode": "MCU3-",
    ...
    "dvdReleaseDate": null,
    "dvdReleaseDateForeign": "2020-04-01",
    "sigmaId": "42653899-4d52-4046-b531-ec5fc544be74",
    "masterVersionId": null,
    ...
}

The YAML has been updated for these changes. The latest version can be retrieved by using the GET /api call.

API developers

The following changes have been made to the YAML:

At line 2907, the sigmaId has been added to the properties of the ContentForGet schema.
At line 2511, the /machines path was added.
At line 2753, the machines property was added to the Content schema.
At line 2947, the machines property was added to the ContentForGet schema.
These were added by mistake as they are not yet supported by the API code.

For easier viewing, the YAMLs can also be compared here: TextCompare

2024r9

Content collection ID in GET products calls of content API

In version 2024r5, the partOfContentCollections array was added to the response of the GET /programs, /episodes and /products calls. This allows users to identify the related content collections of episodes and products more easily.

The array included the contentCollectionId, contentCollectionType and contentCollectionStructure but it did not contain the ID of the content collection items of the program or episode in that content collection.

To be able to retrieve the content collection item ID of a product more easily so it can be used in the /contentCollectionItems calls, the contentCollectionItemIds array has been added to the partOfContentCollections array in the response of the mentioned calls.

It contains the external reference of each content collection item linked to the product in the content collection. It is an array because it is technically possible to add the same product to a content collection twice.

An example of the GET /programs call:

    "partOfContentCollections": [
        {
            "contentCollectionId": "9006311527",
            "contentCollectionType": "season",
            "contentCollectionStructure": "contentCollection",
            "contentCollectionItemIds": [
                "3935562000"
            ]
        },
        {
            "contentCollectionId": "9006329527",
            "contentCollectionType": "season",
            "contentCollectionStructure": "contentCollection",
            "contentCollectionItemIds": [
                "3935572000"
            ]
        },
    ...

The YAML has been updated for these changes. The latest version can be retrieved by using the GET /api call.

API developers

The following has changed in the YAML:

At line 3777, the contentCollectionItemIds was added to the PartOfContentCollection schema.

For easier viewing, the YAMLs can also be compared here: TextCompare

Drop-down calls for clearance windows and YAML correction in content API

In version 2024r7, calls for clearance windows were added to the content API. The POST and PUT /clearanceWindows calls can be used to create or update windows. Their attributes include drop-down lists but the calls to get the available drop-down values were missing.

From this version, calls have been added to retrieve the values for the channelGroups, regionGroups and languageGroups attributes:

  • GET /channelGroups

  • GET /regionGroups

  • GET /languageGroups

The values can be used in the POST and PUT /clearanceWindows calls.

An example of the response of the GET /channelGroups:

[
    {
        "id": "all",
        "name": "All"
    },
    {
        "id": "allLinearAndOnDemand",
        "name": "All linear and on-demand"
    },
    {
        "id": "allLinear",
        "name": "All linear"
    },
    {
        "id": "allOnDemand",
        "name": "All on-demand"
    }
]

Additionally, for the POST /clearanceWindows call, the following attributes are mandatory:

  • contentId

  • startDate

  • endDate

  • channelGroups

However, only the contentId was listed as mandatory in the YAML. This has been corrected.

The YAML has been updated for these changes. The latest version can be retrieved by using the GET /api call.

API developers

The following changes have been done to the YAML:

At line 1621, the startDate, endDate and channelGroups were added to the required section of the clearanceWindows /post call.
From line 2443 to 2500, the drop-down calls were added.

For easier viewing, the YAMLs can also be compared here: TextCompare

2024r7

Clearance windows in content API

Since the previous version, clearance windows can be defined on content.

From this version, calls for clearance windows have been added to the content API.

POST /clearanceWindows

This call is used to create or update a clearance window on content. For creating, the following attributes are mandatory:

  • contentId

  • startDate

  • endDate

  • channelGroups

For updating, the clearanceWindowId should be provided in the body. If the ID cannot be found, a 404 error is returned.

An example of the body:

{
    "contentId": "143048527",    
    "clearanceWindowId": "9501070439",
    "startDate": "2024-08-01",
    "endDate": "2025-07-31",
    "startTime": "10:00:00",
    "endTime": "20:00:00",
    "channelGroups": [
        "allLinearAndOnDemand"
    ],
    "regionGroups": [],
    "languageGroups": [],
    "remarks": null
}

PUT /clearanceWindows/{clearanceWindowId}

This call is used to update an existing clearance window. The external reference or clearanceWindowId must be provided in the URL of the call.

The body is the same as in the POST /clearanceWindows call.

GET /clearanceWindows/{clearanceWindowId}

This call returns the details of a single clearance window. The clearanceWindowId must be provided in the URL of the call.

The response is the same as the body of the POST /clearanceWindows call.

DELETE /clearanceWindows/{clearanceWindowId}

This call deletes the clearance window with the ID provided in the URL of the call.

GET /programs, /episodes and /seasons

The response of these calls has been modified to include the clearance windows of the product. This consists of an array of IDs.

An example of the GET /programs call:

    ...
    "dvdReleaseDate": null,
    "dvdReleaseDateForeign": "2020-04-01",
    "masterVersionId": null,
    "productTitles": [
        {
            "id": "143049544",
            "type": "OriginalTitle",
            "title": "AVENGERS: ENDGAME",
            "alternativeTitle": true,
            "broadcastingTitle": true
        }
    ],
    "partOfContentCollections": [
        {
            "contentCollectionId": "9006564527",
            "contentCollectionType": "season",
            "contentCollectionStructure": "contentCollection"
        }
    ],
    "clearanceWindows": [
        "9501070439",
        "9501070464"
    ]
}

2024r6

Franchises in business API

In this version, the franchise was introduced as an additional content type. Since franchises cannot be

  • created or deleted on the Mediagenix Base platform; or

  • linked to contracts or transmissions;

the following APIs have been adapted to follow this behaviour.

When the external reference of a franchise is provided as contentId, an error message is returned.

For example, GET /products call:

{
    "statusCode": "404",
    "message": "The specified resource does not exist.",
    "timestamp": "2024-05-31T17:42:29Z",
    "concept": "Program",
    "id": "9500899926",
    "errors": [
        {
            "errorCode": "404",
            "description": "The specified resource does not exist.",
            "data": []
        }
    ]
}

The YAML has been updated for these changes. The latest version can be retrieved by using the GET /api call.

API developers

At several places in the YAML, descriptions were added or updated.

From line 1609, the calls for the clearance windows were added.
At line 2920, the reference to the clearance windows was added to the ProgramForGet schema.
At line 2968, the reference to the clearance windows was added to the EpisodeForGet schema.
At line 3037, the reference to the clearance windows was added to the SeasonForGet schema.
At line 3400, the ClearanceWindow schema was added.

For easier viewing, the YAMLs can also be compared here: TextCompare

2024r5

Part of content collections in GET /episodes, programs and products calls of content API

Previously, in the content API, when using a

  • GET /episodes call, only the seasonId and seriesId were returned but nothing related to content collections;

  • GET /programs call, it was not possible to see if the program was part of any content collections.

This also applied to the GET /products call, when the ID of an episode or program was provided.

From this version, the partOfContentCollections array was added to the response of these calls. This allows users to identify the related content collections more easily.

An item is present in the array for each content collection that the episode or program is part of. Each item in the array contains the following attributes:

  • contentCollectionId: The external reference of the content collection.

  • contentCollectionType: The API reference of the type of the content collection, based on the values of the PSIProductType drop-down list. This indicates whether the content collection is on series level or parent series level.

  • contentCollectionStructure: This indicates whether the content collection has the content collection or standard season structure. (RN-5571)

An example of the response of the GET /episodes call:

    "partOfContentCollections": [
        {
            "contentCollectionId": "141638527",
            "contentCollectionType": "season",
            "contentCollectionStructure": "standardSeason"
        },
        {
            "contentCollectionId": "9006188527",
            "contentCollectionType": "series",
            "contentCollectionStructure": "contentCollection"
        },
    ]
}

The YAML has been updated for these changes. The latest version can be retrieved by using the GET /api call.

API developers

The following was changed in the YAML:

Apostrophes were removed around the paths of the different calls.
At line 2670, in the ProgramForGet schema, the reference schema was moved.
At line 2680, in the ProgramForGet schema, the partOfContentCollections property was added.
At line 2723, in the EpisodeForGet schema, the partOfContentCollections property was added.
At line 3413, the PartOfContentCollection schema was added.

For easier viewing, the YAMLs can also be compared here: TextCompare

2024r4

Content warnings in content API and MAM API

It was already possible to manage parental ratings on content and media assets using the content and MAM API. However, it was not yet possible to manage content warnings, which are also defined per regulator on content and media assets. In compliance configuration, the type and format of the content warnings are defined.

From this version, the contentWarnings array has been added to the ratings attribute of the applicable calls.

GET

The contentWarnings array has been added to the response of the following GET calls:

  • Content API:

    • GET /products/{contentId}

    • GET /programs/{contentId}

    • GET /series/{contentId}

    • GET /seasons/{contentId}

    • GET /episodes/{contentId}

    • GET /contentCollections/{contentId}

  • MAM API:

    • GET /mediaAssets/{mediaAssetId}

For each object in the array, it contains the following attributes:

  • id:
    The API reference of the content warning item as defined in the WOnRegulatorComplianceConfigurationEntryField drop-down list.

  • value:
    The value of the content warning. Depending on the type, this will be text, true/false or an array of drop-down values.

  • type:
    The type of the content warning as defined in the compliance configuration: checkBox, dropDown or text.

  • comment:
    The comment on the content warning.

An example of the response of the GET /mediaAssets call:

{
    "mediaAssetId": "6111521000",
    "mediaAssetSequenceId": "6111522000",
    "label": "0000001302",
    "contentId": "143048527",
    "contentTitle": "AVENGERS: ENDGAME",
    "ratings": [
        {
            "regulator": "localRegulator",
            "rating": "6",
            "reason": null,
            "status": null,
            "contentWarnings": [
                {
                    "id": "Violence",
                    "value": true,
                    "type": "checkBox",
                    "comment": "Verified"
                },
                {
                    "id": "Sensitive categories",
                    "value": [
                        "Fear"
                    ],
                    "type": "dropDown",
                    "comment": null
                },
                {
                    "id": "Language",
                    "value": "Harsh",
                    "type": "text",
                    "comment": null
                }
            ]
        }
    ],
    "remarks": null
}

POST and PUT

The contentWarnings array has been added to the body of the following POST and PUT calls:

  • Content API

    • Programs

      • POST /programs

      • PUT /programs/{contentId}

      • POST /programs/{contentId}/versions/{versionId}

    • Series

      • POST /series

      • PUT /series/{contentId}

    • Seasons

      • POST /seasons

      • PUT /seasons/{contentId}

      • POST /seasons/{contentId}/versions/{versionId}

    • Episodes

      • POST /episodes

      • PUT /episodes/{contentId}

      • POST /episodes/{contentId}/versions/{versionId}

    • Content collections

      • POST /contentCollections

      • PUT /contentCollections/{contentId}

  • MAM API

    • POST /completeMediaAssets

    • PUT /completeMediaAssets/{mediaAssetId}

    • POST /mediaAssets

    • PUT /mediaAssets/{mediaAssetId}

For each object in the array, it contains the following attributes:

  • id:

    • This is mandatory and maps to the API reference of the content warning item as defined in the WOnRegulatorComplianceConfigurationEntryField drop-down list.

    • It should be unique per regulator. If the call contains duplicated content warnings for the same regulator, it will fail with the following error:

      {
    "statusCode": "422",
    "message": "Operation cannot be completed due to violations",
    "timestamp": "2024-04-25T12:10:20Z",
    "concept": "MediaAsset",
    "id": "6111521000",
    "errors": [
        {
            "errorCode": "CORE-00011",
            "description": "$_Unprocessable ressource",
            "data": [
                "The call contains multiple references to the same Parental rating identified with Drugs"
            ]
        }
    ]
}

  • value:
    The value of the content warning. Depending on the type, this will be text, true/false or an array of drop-down values. If the wrong input is given for a certain type, an error message is returned. For example:

    {
    "statusCode": "422",
    "message": "Operation cannot be completed due to violations",
    "timestamp": "2024-04-25T12:18:35Z",
    "concept": "MediaAsset",
    "id": "6111521000",
    "errors": [
        {
            "errorCode": "CORE-00002",
            "description": "BOOLEAN: only true or false allowed",
            "data": [
                "Usage"
            ]
        }
    ]
}

  • comment:
    A comment on the content warning.

If the content or media asset already had content warnings and the contentWarnings array is included in the body, the existing list will be removed and replaced by the new one provided as part of the call. Content warnings can be deleted by not including them in the contentWarnings array anymore or by clearing their value.

An example of the PUT /mediaAssets/{mediaAssetId} body:

   "contentId": "143048527",
    "contentTitle": "AVENGERS: ENDGAME",
    "ratings": [
        {
            "regulator": "localRegulator",
            "rating": "6",
            "reason": null,
            "status": null,
            "contentWarnings": [
                {
                    "id": "Violence",
                    "value": true,
                    "comment": "Verified"
                },
                {
                    "id": "Sensitive categories",
                    "value": [
                        "Fear"
                    ],
                    "comment": null
                },
                {
                    "id": "Language",
                    "value": "Harsh",
                    "comment": null
                }
            ]
        }
    ],

When a content warning is included that is not configured for the defined regulator, the following error is returned:

{
    "statusCode": "422",
    "message": "Operation cannot be completed due to violations",
    "timestamp": "2024-04-25T12:34:00Z",
    "concept": "MediaAsset",
    "id": "6111521000",
    "errors": [
        {
            "errorCode": "MAM-00046",
            "description": "$_The content warnings with id  Violence was not found for regulator csaRegulator",
            "data": [
                "Violence",
                "csaRegulator"
            ]
        }
    ]
}

The YAMLs have been updated for these changes. The latest versions can be retrieved by using the GET /api calls of the content and MAM API.

API developers

The following was changed in the YAML of the

  • content API:

At line 918, the reference to the $ref: '#/components/schemas/ProgramVersion' was replaced by $ref: '#/components/schemas/EpisodeVersion'.
At line 2410, the dvdReleaseDate and dvdReleaseDateForeign properties were added to the Content schema. RN-6303
At line 2606, the dvdReleaseDate and dvdReleaseDateForeign properties were added to the ContentForGet schema. RN-6303
At line 2982, the contentWarnings property with 3 reference schemas was added to the Rating schema
The PressSheetCreateOrUpdateSuccess schema was removed.

  • MAM API:

At line 2495, the contentWarnings property with 3 reference schemas was added to the Rating schema.
For easier viewing, the YAMLs can also be compared here: TextCompare

2024r3

DVD release dates in content API

On the Business tab of the product navigator in WHATS'ON Base, dates can be set related to the domestic and international milestones of a product.

From this version, the fields referring to "international" have been renamed to include the term "foreign" to be consistent with the XPaths:

  • International cinema release date > Foreign cinema release date

  • International cinema turnover > Foreign cinema turnover

  • International DVD release date > Foreign DVD release date

  • International release dates are validated > Foreign release dates are validated

Additionally, the dvdReleaseDate and dvdReleaseDateForeign attributes have been added to the response of the GET calls and the body of the PUT and POST calls for programs, episodes, seasons, series and content collections (but not on the GET /contents call).

The attributes map to the Domestic DVD release date and Foreign DVD release date fields respectively and their values require the YYYY-MM-DD format.

An example of the PUT /contentCollections call with the attributes:

{
    "contentId": "9500477768",
    "contentType": "season",
    "title": "FFO 2024",
    "duration": "01:40:00",
    "dvdReleaseDate": "2024-02-01"
    "dvdReleaseDateForeign": "2024-03-01"
}

Due to an error, the YAML has not yet been updated for this change but the fields can be used as described above.

Parameter for version inheritance in content API

Since version 2023r9, it is possible to add the propagateToEpisodes parameter to the URL of the PUT or POST /seasons calls in the content API to configure how inheritance to episodes should happen.

However, in WHATS'ON Base, inheritance can also be set to product versions but this was not yet available in the API.

Therefore, from this version, the propagateToVersions parameter can also be added to the URL of the POST and PUT /seasons, /programs and /episodes calls.

The possible values are:

  • onlyIfValuesAreEqual:

    • This is the default value when the parameter is not provided in the URL.

    • Changes in the body are only propagated when versions have the same value as the master product.
      For example, a program and its versions had a duration of 00:40:00 while one version had a duration of 00:43:00. When the POST call changes the duration of the program to 00:47:00, the program and the versions that had 00:40:00 as duration will be updated.

  • always:
    The changes are always propagated to all the versions, even if it means overwriting different values.

  • never:
    The changes are done only for the master product and are never inherited by the versions.

An example of the URL with the parameter: PUT /programs/{contentId}?propagateToVersions=onlyIfValuesAreEqual

The YAML has been updated for these changes. The latest version can be retrieved by using the GET /api call.

API developers

For API developers, the following section

        - name: propagateToVersions
          in: query
          schema:
            type: string
            enum:
              - always
              - never
              - onlyIfValuesAreEqual
            default: onlyIfValuesAreEqual
            description:
              Changes done to the program are propagated to its versions based on the value of this parameter.

was added to the parameters of

  • /programs:
    post
    At line 101

  • '/programs/{contentId}':
    put
    At line 150

  • /seasons:
    post:
    At line 485

  • '/seasons/{contentId}':
    put
    At line 545

  • /episodes
    post:
    At line 710

  • '/episodes/{contentId}':
    put
    At line 766

For easier viewing, the YAMLs can also be compared here: TextCompare  

Parameters for episode and version inheritance in press sheet calls of content API

Since version 2023r9, it is possible to add the propagateToEpisodes parameter to the URL of the PUT or POST /seasons calls in the content API to configure how inheritance to episodes should happen.

From 2024r3, the propagateToVersions parameter can also be added to the POST and PUT /seasons, /programs and /episodes calls.

However, in WHATS'ON Base, this inheritance also applies to press sheets. Since these are managed using separate calls, this press sheet inheritance was not applied in the API.

From this version, the propagateToEpisodes and propagateToVersions parameters can be added to the URL of the POST and PUT /pressSheets calls.

The possible values are:

  • onlyIfValuesAreEqual:
    When the press sheet is for a series or master product, the changes in the body are only propagated to the press sheets of the episodes or versions when they have the same value as the series or master product.

    For example, a program and its versions had COOKING SHOW as press title while one version had COOKING SHOW FINALE. When the POST call changes the title on the press sheet of the program to COOKING WITH ME, the program and the versions that also had COOKING SHOW as title will be updated. The one with COOKING SHOW FINALE will not be.

  • always:
    The changes are always propagated to the press sheets of all the episodes or versions, even if it means overwriting different values.

  • never:

    • This is the default value when the parameter is not provided in the URL.

    • The changes are done only for the press sheet of the series or master product and are never inherited by the episodes or versions.

An example of the URL with the parameter: PUT /pressSheets?propagateToVersions=never&propagateToEpisodes=never

The YAML has been updated for these changes. The latest version can be retrieved by using the GET /api call.

API developers

For API developers, the following section

        - name: propagateToVersions
          in: query
          schema:
            type: string
            enum:
              - always
              - never
              - onlyIfValuesAreEqual
            default: never
        - name: propagateToEpisodes
          in: query
          schema:
            type: string
            enum:
              - always
              - never
              - onlyIfValuesAreEqual
            default: never

was added to the parameters of

  • /pressSheets:
    post
    At line 1231

  • '/pressSheets/{pressSheetId}':
    put:
    At line 1288

For easier viewing, the YAMLs can also be compared here: TextCompare

Fix for emptying display type in content API

Previously, when using the POST or PUT /programs, /episodes, /seasons, /contentCollections and /series calls of the content API to empty the display type by specifying "displayType": null, the business API service would crash and the following error was returned.

{
    "statusCode": "500",
    "message": "Message not understood: #availableForProductTypes",
    "timestamp": "2024-03-25T09:49:15Z"
}

This issue has been fixed. When "displayType": null is included in the body of the call, the display type of the content is emptied as expected.

2024r2

Parent series not allowed for content collection calls of content API

In a previous version, the content API was adapted for content collections on parent series. They can only be edited by adding or removing items using the /contentCollectionItems calls, not the /series calls.

Since nothing else can be changed on the parent series content collection, it was intended to use the /series calls to update the parent series and not the /contentCollection calls.

However, when the ID (external reference) of a parent series was provided in the URL of the /contentCollection calls, changes were still accepted.

From this version, when the external reference of a parent series is provided in the URL of the GET, POST, PUT or DELETE /contentCollection calls, the following error is returned:

{
    "statusCode": "404",
    "message": "The specified resource does not exist.",
    "timestamp": "2024-03-01T14:33:40Z",
    "concept": "Content Collection",
    "id": "32614015BE",
    "errors": [
        {
            "errorCode": "404",
            "description": "The specified resource does not exist.",
            "data": []
        }
    ]
}

Only the external reference of series (standard seasons or content collections) are now accepted in these calls. Parent series should be updated using the /series calls and /contentCollectionItems calls to add or remove items.

API developers

For API developers: a description was added to the requestBody of the following paths:

  • 855:  '/contentCollections':
  • 856:    post:
    The addition is at line 870
  • 898:  '/contentCollections/{contentId}':
  • 899:    put:
    The addition is at line 911
  • 934:    get:
    The addition is at line 936
  • 984:    delete:
    The addition is at line 986
      requestBody:
        required: true
        description: >
          **Note**: Attribute "ContentId" cannot be the external reference of a parent series. 
          Manipulations on parent series should always be done using the dedicated series call

For easier viewing, the YAMLs can also be compared here: TextCompare