Introduction
This document outlines how we approach developing and supporting multiple API endpoint versions.
Phases of life
| Phase | Description | Feature changes | Security patches |
|---|
| Current | This is the most recent major version of our API | Yes | Yes |
| Deprecated | One major version behind "current" | No | Yes |
| End of life | Endpoints that are no longer supported at all | No | No |
General philosophy
We would like all of our customers to be using the most current version of our API. This is the version that we will be updating with features and actively maintaining.
Deprecated endpoints are available for use (their routes work) but are not actively supported with new features.
Endpoints that are in end of life will be scheduled to be removed from the server, clients making use of them should contact us for help in migrating to more current endpoints.
We will not move an endpoint to "end of life" before consulting with client developers.
Current version lifecycle
Category
| Version | Endpoint | Lifecycle | Documentation |
|---|
| No version | List of categories | Current | List of Categories |
Channel
| Version | Title | Lifecycle | Documentation |
|---|
| 4 | User specified favourite channel lists (REST) | Planned | Favourite channel lists |
| 4 | Channel index (REST) | Planned | Metadata: Channels#/Channels/GetChannelIndex |
| 3.1 | User specific channels | End of Life | User specific channels (v3.1) |
| 3.1 | List of channels | End of Life | List of Channels (v3.1) |
| 2 | List of channels | Current | List of Channels (v2) |
| 2 | Details of channel | Current | Details of Channel (v2) |
| 2 | Play channel | Deprecated | PlayableStream |
| 2.0 | Mark/unmark channel as favourite | Deprecated | Mark/unmark channel as favourite |
| 1.0 | Play Channel | End of Life | Play Channel (deprecated) |
| 1.0 | Adding Channels to be Recorded | End of Life | Adding Channels to be Recorded |
EPG
| Version | Title | Lifecycle | Documentation |
|---|
| 3.0 | EPG List V3 | Current | EPG List V3 |
| 3.0 | EPG Program Details V3 | Current | EPG Program Details V3 |
| No version | EPG List V2 | Deprecated | EPG List V2 |
| 2.0 | EPG V2 - Program Details | Deprecated | EPG V2 - Program Details |
| 2.0 | List of top recordings | Current | List of top recordings |
| 4 | Get a list of broadcast slots | Planned | Schedule#/BroadcastSlots/GetBroadcastSlotsIndex |
| 4 | Get a list of programs with basic metadata | Planned | Metadata: Programs#/Programs/GetProgramIndex |
| 4 | Get details for a specific program including rich metadata relationships | PLanned | Metadata: Programs#/Programs/GetProgram |
| 4 | Get a list of genres | Planned | Metadata: Genres#/Genres/indexGenres |
| 4 | Get a list of programs for a particular genre | Planned | Metadata: Genres#/Genres/SeeGenrePrograms |
| 4 | Get list of programs for a credited person | Planned | /wiki/spaces/MAPI/pages/49676902 |
Teletext
| Version | Title | Lifecycle | Documentation |
|---|
| 2.0 | Teletext Page Item | Current | Teletext Page Item |
| 2.0 | Teletext SubPage Item | Current | Teletext SubPage Item |
| 2.0 | TeleText SubPage Index | Current | Teletext SubPage Index |
| 2.0 | TeleText Create | Current | Teletext Create |
Irdeto Integration
| Version | Title | Lifecycle | Documentation |
|---|
| 2.0 | Associate User with STBDevice | Deprecated | Associate User with STBDevice |
| REST 1.0 | Entitle a set top box to watch DVB channels | Planned | /wiki/spaces/MAPI/pages/49676635 |
| REST 1.0 | Remove entitlement from set top box | Planned | /wiki/spaces/MAPI/pages/49676635 |
Product and Licensing
| Version | Title | Lifecycle | Documentation |
|---|
| 4.0 | Get an index of the licenses that a user has for channels | Planned | Channel License#/Channels/GetUserChannelLicenses |
| 4.0 | Add a new channel license to a user | Planned | Channel License#/Channels/addUserChannelLicenses |
| 4.0 | Remove a channel license from a user. | Planned | Channel License#/Channels/DeleteUserChannelLicenses |
| 4.0 | Fetch a list of recording devices that are available to the user | Planned | /wiki/spaces/MAPI/pages/49676828 |
| 2.0 | List of Products | Current | List of Products |
| 1.1 | List of external VOD Products | Current | List of external VOD Products |
| 2.0 | Details of Products | Current | Details of Products |
| 2.0 | Product Buy Options | Current | Product Buy Options |
| 2.0 | Buy a Product | Current | Buy a Product |
| 2.0 | List of Licenses | Current | List of Licenses |
| 2.0 | Details of License | Current | Details of License |
| 2.0 | Update License | Current | Update License |
| No version | Check License Status | Current | Check License Status |
| No version | Verify App-Store Payment | Current | Verify App-Store Payment |
| 2.0 | Verify Credit Card | Current | Verify Credit Card |
| 2.0 | Booxmedia Product Details | Current | Booxmedia Product Details |
| 2.2 | JWT token for VOD provider product license | Current | JWT token for VOD provider product license |
| 2.0 | SilverHD license | Current | SilverHD license |
| 2.0 | Activate Gameleo license | Current | Activate Gameleo license |
User Management
| Version | Title | Lifecycle | Documentation |
|---|
| 4.0 | Get an index of Users. | Planned | Users#/Users/indexUsers |
| 4.0 | Create a user | Planned | Users#/Users/createUser |
| 4.0 | Get the details for a particular user. | Planned | Users#/Users/getUser |
| REST 1.0 | User Market segmentation (REST) | Current | Users |
| 2.0 | User Login | Current | User Login |
| 2.0 | User Logout | Current | User Logout |
| 2.0 | List of Users | Current | List of Users |
| 2.0 | Add New User Account | Current | Add New User Account |
| 2.0 | Edit Existing User Account | Current | Edit Existing User Account |
| 2.0 | Delete User Account | Current | Delete User Account |
| 2.0 | Request Account Password Reset | Current | Request Account Password Reset |
| 2.0 | Confirm Account Password Reset | Current | Confirm Account Password Reset |
| 2.0 | Delete User Account | Current | Delete User Account |
| 2.0 | Add User Alias | Current | Add User Alias |
| 2.0 | Change User Alias | Current | Change User Alias |
| 2.0 | Delete User Alias | Current | Delete User Alias |
| 2.0 | Link User with User Alias | Current | Link User with User Alias |
| 2.0 | Associate Package with User Alias | Current | Associate Package with User Alias |
| 2.0 | Change Associated Package | Current | Change Associated Package |
| 2.0 | Add Additional Service | Current | Add Additional Service |
| 2.0 | Get Service Status | Current | Get Service Status |
| 2.0 | Logged In User's Service Status | Current | Logged In User's Service Status |
| 2.0 | Update User Service Settings | Current | Update User Service Settings |
| 2.0 | Get User Service Details | Current | Get User Service Details |
| 2.0 | Delete Additional Service | Current | Delete Additional Service |
| 2.0 | Player Consume Minutes | Current | Player Consume Minutes |
| 2.0 | Get Consumed Minutes | Current | Get Consumed Minutes |
| 2.0 | Add STB | Current | Add STB |
| 2.0 | Link STB to User | Current | Link STB to User |
| 2.0 | Remove STB Ownership from an User | Current | Remove STB Ownership from an User |
| 2.0 | OAuth2 User Login (Delta) | Current | OAuth2 User Login (Delta) |
Market segment (client API, not mananagement)
| Version | Title | Lifecycle | Documentation |
|---|
| REST 1.0 | Get the market segments for a particular user | Current | Market segmentation#/Market%20Segmentation/getUserMarketSegments |
Recommendation
| Version | Title | Lifecycle | Documentation |
|---|
| 4.0 | Get a list of populare recordings | Planned | /wiki/spaces/MAPI/pages/49676845 |
| 4.0 | Get a personal recommendation | Planned | /wiki/spaces/MAPI/pages/49676845 |
| 4.0 | Get a personal recommendation from a specific genre | Planned | /wiki/spaces/MAPI/pages/49676845 |
| 4.0 | Send a user event data point to the recommendation engine | Planned | /wiki/spaces/MAPI/pages/49676845 |
| 2.0 | List of Recommendations | Current | List of Recommendations |
| 2.0 | List of Recommendations for Movies | Current | List of Recommendations for Movies |
| 2.0 | List of Recommendations for Season | Current | List of Recommendations for Season |
| 2.0 | List of Recommendations for Series | Current | List of Recommendations for Series |
| 2.0 | List of Recommendations for Episode | Current | List of Recommendations for Episode |
| 2.0 | List of Recommendations for Recording | Current | List of Recommendations for Recording |
Recording
| Version | Title | Lifecycle | Documentation |
|---|
| REST 1.0 | User recording playable streams | Current | PlayableStream related to Recording |
| 4.0 | Get an index of user recording request entities | Planned | /wiki/spaces/MAPI/pages/49676468 |
| 4.0 | Request that a new recording is made | Planned | /wiki/spaces/MAPI/pages/49676468 |
| 4.0 | Get details of a particular recording request | Planned | /wiki/spaces/MAPI/pages/49676468 |
| 4.0 | Cancel a recording request | Planned | /wiki/spaces/MAPI/pages/49676468 |
| 4.0 | Get a list of slots that a device must record (called by STB) | Planned | /wiki/spaces/MAPI/pages/49676468 |
| 4.0 | Update the status of a recording slot (called by STB) | Planned | /wiki/spaces/MAPI/pages/49676468 |
| 4.0 | Get an index of user recording entities | Planned | /wiki/spaces/MAPI/pages/49676468 |
| 4.0 | Update the status of a recording, for example to update how much time the user has watched. | Planned | /wiki/spaces/MAPI/pages/49676468 |
| 4.0 | Delete a recording | Planned | /wiki/spaces/MAPI/pages/49676468 |
| 4.0 | Get a list of tags that have been created for recording requests | Planned | /wiki/spaces/MAPI/pages/49676468 |
| 4.0 | Get a list of recordings that are in a recording group | Planned | /wiki/spaces/MAPI/pages/49676468 |
| REST 1.0 | Update one or more attributes of an existing entity | Deprecated | /wiki/spaces/MAPI/pages/49676468 |
| REST 1.0 | Get a list of recordings that have previously been started | Deprecated | /wiki/spaces/MAPI/pages/49676468 |
| 2.0 | Recording item | Current | Recording item |
| 2.3 | Add Program for Recording | Current | Add Program for Recording |
| 2.3 | Play user recording | Deprecated | Play user recording in favour of PlayableStream related to Recording |
| 2.0 | Logging User Playback | Current | Logging User Playback |
| 2.3 | Update Recorded Content | Current | Update Recorded Content |
| 2.3 | Delete Recorded Content | Current | Delete Recorded Content |
| 2.3 | Search Recorded Content | Current | Search Recorded Content |
| 2.0 | Get list of playheads | Current | Get list of playheads |
| 2.0 | Get specific playhead | Current | Get specific playhead |
| 2.0 | Update Recording Playback position | Current | Update Recording Playback position |
| 2.0 | List of Favorite Recordings | Current | List of Favorite Recordings |
| 2.0 | Update multiple user favourites | Current | Update multiple user favourites |
| 2.2 | Delete Grouped Recorded Content | Current | Delete Grouped Recorded Content |
| 1.0 | List Programs in a Recording Group V1 | Deprecated | List Programs in a Recording Group V1 |
| 1.0 | List Recording Groups and Single Programs V1 | Deprecated | List Recording Groups and Single Programs V1 |
| 2.1 | List Recording Groups and Single Programs V2 | Current | List Recording Groups and Single Programs V2 |
| No version | List Programs in a Recording Group V2 | Current | List Programs in a Recording Group V2 |
| 2.0 | Catchup Program | Current | Catchup Program |
| 2.0 | Catchup Groups collection | Current | Catchup Groups collection |
| 2.0 | Catchup Group item | Current | Catchup Group item |
| 2.1 | Logging Catchup Playback | Current | Logging Catchup Playback |
| 1.2 | Patch User Recordings | Current | Patch User Recordings |
| 1.1 | Get Continue Watching Recordings | Current | Get Continue Watching Recordings |
| 1.1 | Get User Recordings | Deprecated | Get User Recordings |
| 2.0 | User Recording Storage | Current | User Recording Storage |
Ruutu APIs
| Version | Title | Lifecycle | Documentation |
|---|
| 2.1 | Get a Ruutu session for the user | Current | Get a Ruutu session for the user |
| 2.0 | Verify Ruutu Agreement | Current | Verify Ruutu Agreement |
| 2.0 | Get user's Ruutu Licenses | Current | Get user's Ruutu Licenses |
Server
| Version | Title | Lifecycle | Documentation |
|---|
| 2.0 | Get Server Time | Current | Get Server Time |
| 2.0 | Translation | Current | Translation |
| 2.0 | Get Site Images | Current | Get Site Images |
| 2.0 | Application Languages List | Current | Application Languages List |
| 2.0 | Configuration Option List | Current | Configuration Option List |
| 2.0 | Detail of Configuration Option | Current | Detail of Configuration Option |
| 2.0 | GEO Blocking | Current | GEO Blocking |
| 2.0 | VAST Ads | Current | VAST Ads |
| 2.0 | Get server health | Current | Get server health |
| Version | Title | Lifecycle | Documentation |
|---|
| 2.0 | Login | End of Life | Login |
| No version | Logout | End of Life | Logout |
| 2.0 | Proxy Login | End of Life | Proxy Login |
| 2.0 | Twitter | End of Life | Twitter |
Stats
| Version | Title | Lifecycle | Documentation |
|---|
| 2.0 | Create Playback stats log | Current | Create Playback stats log |
STB authentication and functionality
| Version | Title | Lifecycle | Documentation |
|---|
| 2.1 | STB Authentication | Current | STB Authentication |
| 2.0 | Refresh Token | Current | Refresh Token |
| 2.0 | Link STB to User | Current | Link STB to User |
| 2.0 | Remove STB Ownership from an User | Current | Remove STB Ownership from an User |
| 2.0 | Logout STB | Current | Logout STB |
User favourite channels
| Version | Title | Lifecycle | Documentation |
|---|
| 4.0 | An index of all of the favourite channel lists for a specific user | Planned | Favourite channel lists#/Favourite%20Channel%20List%20Collection/indexUserFavouriteChannelList |
| 4.0 | Create a new favourite channel list | Planned | Favourite channel lists#/Favourite%20Channel%20List%20Collection/createFavouriteChannelList |
| 4.0 | Delete a favourite channel list | Planned | Favourite channel lists#/Favourite%20Channel%20List%20Resource/deleteFavouriteChannelList |
| 4.0 | Update a favourite channel list | Planned | Favourite channel lists#/Favourite%20Channel%20List%20Resource/updateFavouriteChannelList |
| 4.0 | A list of ALL the channels that a user has marked as favourite in ANY list. | Planned | Favourite channel lists#/Favourite%20Channel%20List%20Relationships/indexChannelListContents |
| 4.0 | An index of all of the channels that a list contains. | Planned | Favourite channel lists#/Favourite%20Channel%20List%20Relationships/indexChannelListContents |
| 4.0 | Remove a channel from a favourite list | Planned | Favourite channel lists#/Favourite%20Channel%20List%20Relationships/deleteFavouriteChannelItem |
| 4.0 | Add a channel into a favourite list | Planned | Favourite channel lists#/Favourite%20Channel%20List%20Relationships/createFavouriteChannelListItem |
User
| Version | Title | Lifecycle | Documentation |
|---|
| REST 1.0 | Get the details for a particular user (accepts id or email as identifier) | Current | User information v1#/Users/getUser |
| 2.0 | User Registration | Current | User Registration |
| 1.0 | Get Users | Current | Get Users |
| 1.0 | Get User By ID | Current | Get User By ID |
| 2.0 | PIN Code Verification | Current | PIN Code Verification |
| 2.0 | PIN Code Reset Request | Current | PIN Code Reset Request |
| 2.0 | PIN Code Reset/Update | Current | PIN Code Reset/Update |
| 2.0 | Parental PIN Code Reset/Update | Current | Parental PIN Code Reset/Update |
| 2.0 | Verify Parental PIN Code | Current | Verify Parental PIN Code |
| 2.0 | Parental PIN code reset request | Current | Parental PIN code reset request |
| 2.0 | Get age limit | Current | Get age limit |
| 2.0 | Set age limit | Current | Set age limit |
Verimatrix APIs for DRM content
Version | Title | Lifecycle | DocumentationCurrent version lifecycle
Category
| Version | Endpoint | Lifecycle | Documentation | EOL |
|---|
| No version | List of categories | End of Life | List of Categories | June 2021 |
Channel
EPG
Teletext
Product and Licensing
User Management
Recording
Catchup
Playable streams
Ruutu APIs
Server
Playback info
STB authentication and functionality
User favourite channels
User
DRM
VoD
Wallet
Wallet
Stream (replaces "play" endpoints)
| Version | Title | Lifecycle | Documentation |
|---|
| REST 1.2 | Stream List of Channel | Current | Stream List of Channel |
| REST 1.2 | Stream List of Recording | Current | Stream List of Recording |
| REST 1.1 | Stream List of User Recording | Current | Stream List of User Recording |
Authentication / Session management
| Version | Title | Lifecycle | Documentation |
|---|
| 4.0 | Create a user session ("login") in the middleware and receive a session cookie | Planned | User login |
4.0 | Delete a user session in the middleware ("logout") | Planned | User login