UNIAPI Specification

Introduction

This document includes basic API definitions for the UNI API, including protocols, method calling conventions, data exchange formats, methods, data objects and enumerations. It is assumed that the reader is familiar with the encoding of objects using JSON (http://www.json.org/). This document will use its notation when describing data results.

Overview

The API is exposed as a REST service. It receives the parameters through the URL and a query-string, and it returns response data using a JSON-encoded string. To ensure that only authorized clients can access the API, all operations require an identifier composed of a “ConsumerKey“ and “ConsumerSecret“, which are unique for each client application accessing the API. These are also be used to sign the URL using OAuth and HMAC-SHA1 signatures. Access to the API can only be performed through HTTP and HTTPS protocol. Different methods may accept both protocols, or may require the secure version.

URL Structure

Each service has a different root URL, such as: http://api_environment_url/AuthenticationService.svc/ http://api_environment_url/ChannelService.svc/ http://api_environment_url/MovieService.svc/

The service can use separate URLs for different services, to allow better load balancing of high-load methods. However, this feature is currently not being used. The URLs vary depending on the environment (dev, cert, preprod, prod) and the device type (there is load balancing at client level) It’s recommended that any application consuming the UNI API include a centralized and easy to update configuration for the service URLs, to simplify switching between development and production environments.

To access a method, the client application must construct the URL by appending the method name to the root URL, such as: http://api_environment_url/ChannelService.svc/GetChannel

Parameters are sent as part of the querystring: http://api_environment_url/ChannelService.svc/GetChannel?token=c2FtcGxlIHJlbmV3ZWQgdG9rZW4&channelId=102

The URL must then be signed using the method described in the OAuth Signature section. The API signature process can also be disabled for debugging purposes.

OAuth Signature

To prevent the usage of the API by unauthorized parties, all requests must be signed using a valid ConsumerKey/ConsumerSecret pair, using the HMAC-SHA1 signing method described by the OAuth 1.0 specification.

More details about OAuth can be found at: http://oauth.net/, where you can find also some implementations in different languages.

The ConsumerKey and ConsumerSecret vary depending on the environment and applications should not expose this information (at least the ConsumerSecret) outside the application as then the security would be compromised.

If you are starting to develop an application, please request your ConsumerSecret and ConsumerKey to be generated for the different environments by sending an email to gvp@tid.es.

Please notice that it is not required a complete implementation of the OAuth authentication protocol, only the signature algorithm to be applied to the requests. It’s important to remark that the “oauth_consumer_key” must be sent in every request, even if the API call does not required a signature.

A sample for the OAuth signature process can be found here

GET and POST Support

Depending on the API method, the use of the POST method may be required. When performing a call using POST, the device must:

Generate the signature as if all the parameters were to be sent over query-string
Send the entire data in the form body, using the same format as if the data was to be sent over a query-string

In other words, take this request:

Method: GET

URL: http://api_environment_url/ChannelService.svc/GetChannel?token=c2FtcGxlIHJlbmV3ZWQgdG9rZW4&channelId=102

Body: <Empty String>

It can be sent as POST using this format:

Method: POST

URL: http://api_environment_url/ChannelService.svc/GetChannel

Body:token=c2FtcGxlIHJlbmV3ZWQgdG9rZW4&channelId=102

Currently (as for GVP 2.4) don't require POST for any method request. GET can be used for all UNIAPI requests.

It is important to remark that the usage of url encode functions is recomendable for those parameters that might contain special characters.

Authentication

UNI API methods that require any kind of user identification or filtering require a Token parameter. This is necessary even for anonymous users. This token parameter is URL-safe, and doesn’t need to be url encoded before passing it through the request.

Currently, several authentication methods supported:

Anonymous
Username/Password
ApplicationToken
Trusted Device (DeviceId)

To use the Trusted Device authentication method, the device must first be linked to the user. The user can register the device through two different processes:

Using the Website: Device requests a Challenge Code, that has to be entered in the website to allow device registration.
Without using the Website: The device itself asks the user for the Username/Password, performs authentication, then request the registration of the DeviceId associated to this user account.

Regardless of which authentication method was used, the token has the same format and this token may be used for all other API methods.

The token has a time-based expiration, which is also be reported by the authentication methods.

A token renewal method (Renew) is also be available, and it’s recommended that the client device uses it to renew the token before expiration.

If any client accessing UNI API receives a “Expired Token” or “Invalid Token” error, it is be expected to start over the authentication process from one of the login methods.

Multi-Instance Support

Due to the need of having different content available to different countries, the authentication methods require an InstanceId parameter. An instance is an identification code for a country or group of countries that has a specific service settings.

This allow to use a single, shared database for all countries where the Product is deployed, even if parts of the video library are only available for a restricted subset of countries.

An instance also includes some default properties for that particular region, such as the default language. We call this Instance Settings

Multi-Platform Support

Inside an Instance, it is supported the concept of multiple “Platforms”, to allow the usage of different authentication/provisioning/billing platforms in the same Instance.

This option is only available only for Telefonica users. For non-Telefonica users the “platformId” is always equal to zero.

Starting from version 1.12, platform is no longer exposed through the UNI API, and it’s only used in the communication between the MIB backend and GAL (for OSS/BSS integration)

Multi-Language Support

All methods in the API support an LanguageId parameter informing in which language the metadata to be retrieved. It is also used to translate the status messages returned by the API. To simplify the notation it is omitted from the individual method specifications, but you can safely assume this parameter is present and is always accepted by all methods.

If the LanguageId parameter is omitted but a token parameter is present, the default language for the instance used in the authentication process is used. If neither of these parameters is present the API assumes the language to be English..

The LanguageId parameter, if present, has precedence over the token parameter, allowing a client application to override the default language for that particular instance.

Registration

The fields required by the registration process will be different depending on the instance in use. In order the support this, the device is expected to perform the following process when attempting to register an user:

Obtain instance where the user will be registered, either by Geolocation or by requesting to the user directly
Request from the API the list of fields to be used in the registration form
Collect the information from the user
Post the information to the API for user registration

The following fields are assumed to be the “minimum” that must be present in the registration form of all instances:

First Name
Last Name
E-mail
Password
Repeat Password
Adult Confirmation
Mobile Number
Birth Date
Gender

TV Series Handling

A TV Series can be accessed in three different manners:

By Series
By Seasons
By Episodes

In this API, all of these are also represented by the Movie object. The Type property identifies what type of object is being dealt with. All objects that return a list of movies also offer the possibility of filtering by type.

Playback can only be requested for an Episode. Series and Seasons are only used by navigation.

Purchase

The API is being designed assuming that the purchase process gives an instantaneous response. Non-Telefonica users can only make purchases from devices using credit already in their e-wallet.

Analytics

The analytics API is based on a generic “Event Collector” method. An event is defined of a unique string identifier and a well-defined JSON object including the properties for this particular event.

Developers working on client device implementations are encouraged to send events as often as possible, and are also encourage to propose additional events that would be helpful in monitoring the health of the platform, or would help diagnose problems with devices.

The event API has the “token” parameter marked as optional, however devices are required to send this parameter whenever available. Events without token should only happen on the very rare circumstances where the device has access to the API but cannot perfom any kind of authentication.

A section will list the events required by the platform, as well as the accompanying data structures.

Globalization and Culture Info

Dates and Times All dates and times will be reported by the service in the UTC (GMT) timezone. It’s the responsibility of the client application to adjust them to the user’s timezone before displaying. Values will be returned as posix time, which is defined as the number of number of seconds elapsed since the reference date of January 1st, 1970, 00:00 GMT. It’s recommended that both the server and the client applications use a Time Server to maintain its current time and timezone information up-to-date. We also recommend that all APIs implement a public, non-signed method informing the current time in the server.

Floating-Point Numbers All floating-point numbers (float/single, double, decimal/fixed) will use a dot (“.”) as a decimal separator. There will be no separator for thousands.

Strings All text will be encoded using UTF-8.

URL Whenever a URL is specified, will be an absolute URL including domain and full path.

TimeSpan All representations of elapsed time (movie length, rental duration) will be represented as an integer with the total of elapsed seconds.

Session Cookie generation

Until GVP 2.4, the load balancing sticky mode was being controlled through a cookie generated by the IIS. However, the IIS was not able to set the cookie domain name, and thus, the devices accessing through cross domain were not able to access this cookie. Due to this, those devices didn't send the cookie back in their requests, what caused the IIS to generate new cookies all the time and the sticky session was not effective. In GVP 2.4, this cookie generation has been implemented at UNIAPI level, which allows to set domain name in the response. This is configure in the UNIAPI configuration, at GvpApiConfig.mibconfig file.

Set-Cookie:ASP.NET_SessionId=va5f2no2svtlfjpex5zhhth1; path=/; HttpOnly; domain: ucand.gvp.telefonica.com