login
The login "Node" allows an IceTV user to create a token to use with the system, or create a new account in the system.
|
URL |
Description |
|
login |
Retrieve a token for an existing user or create an account for a new user (and a token) |
login (new user)
|
URL |
https://api.icetv.com.au/login |
|
Method |
POST (NOTE: PUT is acceptable) |
|
Query String |
|
|
Returns |
201 OK & Document (XML or JSON) |
|
|
401 Unauthorized |
|
|
404 Not Found |
|
|
406 Not Acceptable |
|
|
503 Service Unavailable |
NOTE: The examples below show both an account being created, and a recording device being attached at the same time. The requests also only show the minimum amount of information required to create an account.
If the IceTV user is logging in on a TV Recorder then a device record MUST be included with the login request, the IceTV server will use the device UID to match this up to any previously created devices, if it does not exist already it will be created.
If you are registering a new account and a recording device record is not included, then a recording device will not be created and will not be included in the reply.
The member reply example shows all fields that are acceptable during creation of a new account, all fields except "id", "token", "token_expiry", and "timezone" can be sent as part of the request.
The device reply shows additional fields, but these are read only fields, the information requires is "uid" or "label" (or both), uid is preferred and must be unique and repeatable on the same recording device, MAC address is good example.
POST https://api.icetv.com.au/login?api_key=API_KEY&application_version=APPLICATION_VERSION
<login> <member email_address="foo@bar.com" password="foo" region_id="1" /> <device uid="b8:f6:b1:18:54:f5" label="DEVICE0" type_id="18" /></login><?xml version="1.0" encoding="UTF-8" standalone="no"?><!DOCTYPE login SYSTEM "http://iceguide.icetv.com.au/iceguide/login.dtd"><login> <member id="51" token="82db0167-0b1c-45af-9899-4cf7311564ab" token_expiry_date="2145916800" region_id="1" timezone="Australia/Sydney" email_address="foo@bar.com" first_name="" last_name="" address_1="" address_2="" city="" state="" postcode="" phone="" dob="0000-00-00" gender="" movie_prefix="true" subscribed_to_marketing_emails="true" subscribed_to_timer_errors="false" subscribed_to_inactive_reminders="true" can_record="true" /> <type id="18" manufacturer_id="7" manufacturer_name="Topfield" manufacturer_url="" model="TRF-2460" notes="Topfield TRF-2460" can_have_device_sub="0" /> <device id="49" uid="b8:f6:b1:18:54:f5" index="0" label="DEVICE0" type_id="18" /></login>JSON - Structure of the request
|
Name |
Type |
Description |
Comment |
|
member |
table |
The member info |
At least an email_address, a password and a region_id are required to create a new account |
|
device |
table |
The device info |
This table MUST be included if the logging app is a recording app |
{ "member": { "email_address" : "foo@bar.com", "password": "foo", "region_id":"1" }, "device": { "uid": "b8:f6:b1:18:54:f5", "label":"DEVICE0", "type_id":"18" }}JSON - Structure of the response
|
Name |
Type |
Description |
Comment |
|
member |
table |
The member info |
Token can be cached |
|
types |
array |
the type of device used to log on |
Array of one element |
|
device |
table |
The device info |
This table MUST be if the logging app is a recording app |
{ "member": { "token": "e9a1ca5e-feea-4df7-b9fd-4fcdbd59a0ee", "token_expiry_date": 2145916800, "region_id": "1", "timezone": "Australia/Sydney", "email_address": "foo@bar.com", "first_name": "", "last_name": "", "address_1": "", "address_2": "", "city": "", "state": "", "postcode": "", "phone": "", "dob": "", "gender": "", "movie_prefix":"Yes", "subscribed_to_marketing_emails":"Yes", "subscribed_to_timer_errors":"No", "subscribed_to_inactive_reminders":"No", "can_record":"Yes" }, "types": [ { "id": "18" "manufacturer_id": "7" "manufacturer_name": "Topfield" "manufacturer_url": "" "model": "TRF-2460" "notes": "Topfield TRF-2460" "can_have_device_sub": "0" } ], "device": { "id": 51, "uid": "b8:f6:b1:18:54:f5", "index": 0, "label": "DEVICE0", "type_id": 18, }}login (existing user)
|
URL |
https://api.icetv.com.au/login |
|
Method |
POST (NOTE: PUT is acceptable) |
|
Query String |
|
|
Returns |
200 OK & Document (XML or JSON) |
|
|
401 Unauthorized |
|
|
404 Not Found |
|
|
406 Not Acceptable |
|
|
503 Service Unavailable |
NOTE: The two differences when an existing user is logging (from an account creation) are:
-
the region_id in the member table does not have to be included
-
The return code, 200 (OK)
POST https://api.icetv.com.au/login?api_key=API_KEY&application_version=APPLICATION_VERSION
<login> <member email_address="foo@bar.com" password="foo" /> <device uid="b8:f6:b1:18:54:f5" label="DEVICE0" type_id="18" /></login><?xml version="1.0" encoding="UTF-8" standalone="no"?><!DOCTYPE login SYSTEM "http://iceguide.icetv.com.au/iceguide/login.dtd"><login> <member id="51" token="82db0167-0b1c-45af-9899-4cf7311564ab" token_expiry_date="2145916800" region_id="1" timezone="Australia/Sydney" email_address="foo@bar.com" first_name="" last_name="" address_1="" address_2="" city="" state="" postcode="" phone="" dob="0000-00-00" gender="" movie_prefix="true" subscribed_to_marketing_emails="true" subscribed_to_timer_errors="false" subscribed_to_inactive_reminders="true" can_record="true" /> <type id="18" manufacturer_id="7" manufacturer_name="Topfield" manufacturer_url="" model="TRF-2460" notes="Topfield TRF-2460" can_have_device_sub="0" /> <device id="49" uid="b8:f6:b1:18:54:f5" index="0" label="DEVICE0" type_id="18" /></login>JSON - Structure of the request
|
Name |
Type |
Description |
Comment |
|
member |
table |
The member info |
At least the email_address and the password are required to log in |
|
device |
table |
The device info |
This table MUST be included if the logging app is a recording app |
{ "member": { "email_address" : "foo@bar.com", "password": "foo" }, "device": { "uid": "b8:f6:b1:18:54:f5", "label":"DEVICE0", "type_id":"18" }}JSON - Structure of the response
|
Name |
Type |
Description |
Comment |
|
member |
table |
The member info |
The token can be cached |
|
types |
array |
the type of the device used to log on |
Array of one element |
|
device |
table |
The device info |
This table MUST be if the logging app is a recording app |
{ "member": { "id": 52, "token": "e9a1ca5e-feea-4df7-b9fd-4fcdbd59a0ee", "token_expiry_date": 2145916800, "region_id": 1, "timezone": "Australia/Sydney", "email_address": "foo@bar.com", "first_name": "", "last_name": "", "address_1": "", "address_2": "", "city": "", "state": "", "postcode": "", "phone": "", "dob": "", "gender": "", "movie_prefix":"Yes", "subscribed_to_marketing_emails":"Yes", "subscribed_to_timer_errors":"No", "subscribed_to_inactive_reminders":"No", "can_record":"Yes" }, "types": [ { "id": 18, "manufacturer_id": 7, "manufacturer_name": "Topfield", "manufacturer_url": "", "model": "TRF-2460", "notes": "Topfield TRF-2460", "can_have_device_sub": 0 } ], "device":{ "id": 51, "uid": "b8:f6:b1:18:54:f5", "index": 0, "label": "DEVICE0", "type_id": 18, "manufacturer": "Topfield", "model": "TRF-2460" }}