Platform DocsPlayers DocsRelease Notes
System StatusSubmit a CaseDashboard LoginContact Sales

Migrate to Management API v2

Learn how to migrate from Platform Management API v1 to API v2

Overview

The Platform Management API enables you to programmatically modify many of your JW Player products and features. While maintaining this functionality, the Platform Management API v2, improves security and adheres to consistent design principles.


Improved security

Instead of using signature-based authentication, the Platform Management API v2 uses a simpler Bearer authentication. This new API version also gives you greater control over your keys and access control.

v2 v1
Authentication Bearer authentication Signature-based authentication
Number of API keys Multiple API credentials per site Single site credential
API key replacement Compromised keys can be deleted and new keys created by an admin user A compromised key requires contacting JW Player Support
Access Control Ability to define the user role and sites to which an API key has access API key has full account access and applies to a single site

Adherence to consistent design

The Platform Management API v2 is a RESTful API structured around resources. HTTPS verbs are associated with one of several types of routes. Request bodies are standardized. The query parameter q has been added to provide powerful options to filter results.

v2 v1
HTTPS verbs Standard association of GET, POST, PATCH, PUT, and DELETE with types of routes Inconsistent usage that relies heavily upon GET and POST
Request body JSON payloads that contain one or more of the following attributes: metadata, upload, and relationships Payloads with an inconsistent structure
Search Query parameter q that provides powerful filtering options Unique query parameters for each querying option with no complex filtering options

Quick Start

To quickly get started with the Platform Management API v2, we suggest the following steps:

  1. Familiarize yourself with the API v2 authentication.
  2. Choose one of our Platform Management API v2 client libraries. These libraries help you to quickly incorporate products, features, and functionality into your existing workflow.

🚧

If you currently use an officially supported client library, you will need to update the version being used.


If you have a specialized implementation of JW Player's Platform Management API v1, we recommend reviewing the following Detailed Changes section.


Detailed Changes

In addition to the aspects highlighted in the overview, changes have been made in the following areas to provide a consistent design:

The following sections detail the important changes that have been made.


Resources

v1 v2
--- account

When creating or modifying an account resource, the following concepts have changed:
   • An account may contain multiple sites.
   • An account is the same as a JW Player dashboard
account site

The site resource replaces the v1 account resource.
channel playlist

When creating or modifying a playlist resource, the following parameters have changed:
   • The query parameter type in v1 is now the path parameter playlist_type.
   • Custom parameters (accessed as custom.{param}) are now a single field called custom_params.
   • With the exception of author, description, link, and title, all other fields have been moved to the subresource for each playlist type (article matching, dynamic, manual, recommendations, search, and trending).
conversion originals

Original conversions are now available via a separate originals endpoint. All other conversions are now referred to as media_renditions.

When creating or modifying an original resource the following parameter has changed:
   • The template field has been removed.
media_renditions

When creating or modifying a media_renditions resource the following parameters have changed:
   • The duration field has been removed from media_renditions and is only available on originals.
   • The template field has been removed.
   • The link field has been replaced with a single string field delivery_url.
   • The filesize field is now an integer instead of a string.
player player

When creating or modifying a player resource the following parameters have changed:
   • Custom parameters (accessed as custom.{param}) are now a single field called custom_params.
   • With the exception of release_channel and name, all other fields have been moved to the setup_config object.
tag N/A

Tags are no longer a resource. They are an attribute of other resources such as media.
thumbnail thumbnail

The thumbnail resource provides different functionality:
   • A thumbnail can be explicitly chosen to be the poster for a media.
   • A list of previous thumbnails can be retrieved.
track text_track

When creating or modifying a text_track resource, the following parameters have changed:
   • The link object is now a single string field called delivery_url.
   • The md5 and size fields have been removed.
usage N/A

Usage is now retrieved via an action endpoint.
video media

When creating or modifying a media resource, the following parameters have been renamed:
   • The date field has been renamed publish_start_date.
   • The error field has been renamed error_message.
   • The expires_date field has been renamed publish_end_date.
   • The link field has been renamed permalink.
   • The mediatype field has been renamed media_type.
   • The sourceformat field has been renamed mime_type.
   • The sourcetype field has been renamed hosting_type.

The following parameters have changed:

   • Custom parameters (accessed as custom.{param}) are now a single field called custom_params.
   • The md5 and size fields have been removed.
   • The upload configuration fields (method, mime_type, source_url, download_url, trim_in_point, trim_out_point) are now in a separate upload object. Learn about uploading content in API v2.

Routes

/v1/accounts/

v1 v2
/v1/accounts/tags/create Not supported
/v1/accounts/tags/delete PUT /v2/sites/{site_id}/remove_tag/
/v1/accounts/tags/list Not supported
/v1/accounts/tags/show Not supported
/v1/accounts/tags/update PUT /v2/sites/{site_id}/rename_tag/
/v1/accounts/usage/show PUT /v2/sites/{site_id}/query_usage/

/v1/channels

v1 v2
/v1/channels/create POST /v2/sites/{site_id}/playlists/{playlist_type}/
/v1/channels/delete DELETE /v2/sites/{site_id}/playlists/{playlist_id}/

OR

DELETE /v2/sites/{site_id}/playlists/{playlist_id}/{playlist_type}/
/v1/channels/list GET /v2/sites/{site_id}/playlists/
/v1/channels/show GET /v2/sites/{site_id}/playlists/{playlist_id}/

OR

GET /v2/sites/{site_id}/playlists/{playlist_id}/{playlist_type}/
/v1/channels/update PATCH /v2/sites/{site_id}/playlists/{playlist_id}/{playlist_type}/
/v1/channels/videos/create PATCH /v2/sites/{site_id}/playlists/{playlist_id}/{playlist_type}/
/v1/channels/videos/delete PATCH /v2/sites/{site_id}/playlists/{playlist_id}/{playlist_type}/
/v1/channels/videos/list PATCH /v2/sites/{site_id}/playlists/{playlist_id}/{playlist_type}/
/v1/channels/videos/show PATCH /v2/sites/{site_id}/playlists/{playlist_id}/{playlist_type}/
/v1/channels/videos/update PATCH /v2/sites/{site_id}/playlists/{playlist_id}/{playlist_type}/

/v1/players

v1 v2
/v1/players/create POST /v2/sites/{site_id}/players/
/v1/players/delete DELETE /v2/sites/{site_id}/players/{player_id}/
/v1/players/list GET /v2/sites/{site_id}/players/
/v1/players/show GET /v2/sites/{site_id}/players/{player_id}/
/v1/players/update PATCH /v2/sites/{site_id}/players/{player_id}/

/v1/status

v1 v2
/v1/status Not supported

/v1/videos

v1 v2
/v1/videos/create POST /v2/sites/{site_id}/media/
/v1/videos/delete DELETE /v2/sites/{site_id}/media/{media_id}/
/v1/videos/list GET /v2/sites/{site_id}/media/
/v1/videos/show GET /v2/sites/{site_id}/media/{media_id}/
/v1/videos/update PATCH /v2/sites/{site_id}/media/{media_id}/
/v1/videos/conversions/create POST /v2/sites/{site_id}/media/{media_id}/media_renditions/
/v1/videos/conversions/delete DELETE /v2/sites/{site_id}/media/{media_id}/media_renditions/{rendition_id}/
/v1/videos/conversions/list GET /v2/sites/{site_id}/media/{media_id}/originals/

AND

GET /v2/sites/{site_id}/media/{media_id}/media_renditions/
/v1/videos/conversions/show GET /v2/sites/{site_id}/media/{media_id}/media_renditions/{rendition_id}/
/v1/videos/tags/list Not supported
/v1/videos/thumbnails/show GET /v2/sites/{site_id}/thumbnails/{thumbnail_id}
/v1/videos/thumbnails/update POST /v2/sites/{site_id}/thumbnails/

AND

PATCH /v2/sites/{site_id}/thumbnails/{thumbnail_id}
/v1/videos/tracks/create POST /v2/sites/{site_id}/media/{media_id}/text_tracks/
/v1/videos/tracks/delete DELETE /v2/sites/{site_id}/media/{media_id}/text_tracks/{track_id}/
/v1/videos/tracks/list GET /v2/sites/{site_id}/media/{media_id}/text_tracks/
/v1/videos/tracks/show GET /v2/sites/{site_id}/media/{media_id}/text_tracks/{track_id}/
/v1/videos/tracks/update PATCH /v2/sites/{site_id}/media/{media_id}/text_tracks/{track_id}/

Parameters

v1 v2
custom parameters

{
  "custom.example1": "value",
  "custom.-example2": null
}

If a parameter already exists in the database, it will be updated with the new value.

If a parameter name starts with -, parameter with the same name (but without leading -) will be deleted from the database.

custom parameters

{
  "metadata": {
    "custom_params": {
      "example1": "value"
    }
  }
}

When updating existing custom_params, include all custom_params keys with their updated values.

Any custom_params key-value pair not included within the updated custom_params in the request body is deleted.

keyid
metadata

{
  "name": "Example player",
  "release_channel": "latest",
  "aspectratio": "16:9",
  "responsive": true,
  "autostart": false,
  "displaydescription": true,
  "displaytitle": true,
  "playback_rate_controls": true,
  "preload": "metadata",
  "repeat": false,
  "stretching": "uniform"
}

metadata

{
    "metadata": {
        "name": "Example player",
        "release_channel": "latest",
        "setup_config": {
            "aspectratio": "16:9",
            "responsive": true,
            "autostart": false,
            "displaydescription": true,
            "displaytitle": true,
            "playbackRateControls": true,
            "preload": "metadata",
            "repeat": false,
            "stretching": "uniform"
        }
    }
}

With the exception of release_channel and name, all other fields have been moved to the setup_config object. This change enables support for any options available in the player but removes API validation.


Error Messaging

The response format of API errors has changed.

v1 v2 
{
  "code": "ServerError",
  "message": "Something went wrong!"
}

This format only contains a single error at a time. If there were multiple errors with your request it could be a tedious process to address them one at a time.

 
{
    "errors": [{
        "code": "server_error",
        "description": "Something went wrong!"
    }]
}

Multiple errors may be returned in a single response. This allows you to see and respond to multiple errors with your request at once.

The code field still refers to a short string intended for automation while description (formerly message) is a human-readable explanation.