API 20131021 will implement a REST interface

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

API 20131021 will implement a REST interface

Post by rkulagow » Thu Jan 23, 2014 8:19 am

On the beta server, (http://23.21.174.111) a REST interface will be used to manage accounts, to download data, etc.

POST /20131021/token HTTP/1.1
Host: 23.21.174.111
Cache-Control: no-cache

{"username":"rkulagow@rocketmail.com", "password":"d74952c4fbc3ee3713d30423e0071544d1c4f7b0"}

Response:

{
"serverID": "AWS-micro.1",
"token": "9946b430c100b1d104d42741ced71341"
}

The token is then used for subsequent calls and is set in the header.

To get status, use the following:

GET /20131021/status HTTP/1.1
Host: 23.21.174.111
token: 9946b430c100b1d104d42741ced71341
Cache-Control: no-cache

{
"account": {
"expires": "2014-06-28T05:16:29Z",
"messages": [
{
"msgID": "1234567890123456789012",
"date": "2013-11-15T19:49:53Z",
"message": "This is a test of the message function."
}
],
"maxLineups": 16,
"nextSuggestedConnectTime": "2014-01-24T01:39:50Z"
},
"lineups": [
{
"ID": "USA-IL57303-X",
"modified": "2014-02-16T06:49:01Z",
"uri": "/20131021/lineups/USA-IL57303-X"
},
{
"ID": "USA-OTA-60030",
"modified": "2014-02-16T06:50:55Z",
"uri": "/20131021/lineups/USA-OTA-60030"
}
],
"lastDataUpdate": "2014-01-22T15:30:52Z",
"notifications": [],
"systemStatus": [
{
"date": "2012-12-17T16:24:47Z",
"status": "Online",
"details": "All servers running normally."
}
],
"serverID": "AWS-micro.1"
"code":0
}

You can also obtain the list of subscribed headends:

GET /20131021/headend HTTP/1.1
Host: 23.21.174.111
token: 9946b430c100b1d104d42741ced71341
Cache-Control: no-cache

{
"serverID": "AWS-micro.1",
"datetime": "2014-01-23T15:16:01Z",
"data": [
{
"headend": "IL57303",
"name": "Comcast Waukegan/Lake Forest Area",
"location": "Lake Forest"
},
{
"headend": "PC:60030",
"name": "Antenna",
"location": "Over-the-air"
}
]
}

Additional methods to add/delete headends, to retrieve lineups and to perform other functions are being developed.

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: API 20131021 will implement a REST interface

Post by rkulagow » Fri Feb 07, 2014 9:38 am

UPDATE: examples of methods.

http://23.21.174.11/20131021/ is the baseline URL for the following:

POST /token
The body needs to be JSON:
{"username":"rkulagow@rocketmail.com", "password":"b14952c3a9c3ee3717a30723e1b71544d1c4d7b0"}

The submitted password must be the sha-1 hex of the user's password.

Body returns the token for the user.

GET /status
header must contain "token" with a valid token:

GET /20131021/status HTTP/1.1
Host: 23.21.174.111
token: ec32c302bd7b203ff0b0faa9f1f3cd1e
Cache-Control: no-cache

Returns JSON information about messages, account expiration, etc.

GET /headends?country=3-letter-country&postalcode=postalcode
header must contain "token" with a valid token
Returns the lineups in a postal code.

The three-letter country code is ISO-3166-1 Alpha 3. See http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3

Headends are different than lineups. A lineup is a specific instance of a headend and includes the device.

For a cable lineup, the "DEFAULT" device would be whatever content you can obtain without a set top box directly over the wire.

GET /lineups
header must contain "token" with a valid token
Returns JSON about the lineups the user has subscribed to in their account

PUT /lineups/COUNTRY-HEADEND-DEVICE
header must contain "token" with a valid token
Adds a lineup to the user's account

DELETE /lineups/COUNTRY-HEADEND-DEVICE
header must contain "token" with a valid token
Deletes a lineup from user's account

GET /lineups/COUNTRY-HEADEND-DEVICE
header must contain "token" with a valid token
Returns stationID / channel mapping for the lineup

POST /programs
header must contain "token" with a valid token
body is JSON that looks like this:
{"request":["EP000000211560","EP000000211567"]}

The server will return JSON for the programs you've requested. Limit chunk size to 5000 programs per request. The response will be a flat text file; each line will be a single JSON object terminated by newline.

POST /schedules
header must contain "token" with a valid token
body is JSON that looks like this:
{"request":[20454,10002]}

The server will return JSON for the stationIDs you've requested.

DELETE /messages/{msgid}
header must contain "token" with a valid token
Deletes msgid from the returned status. (ACK a message)

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: API 20131021 will implement a REST interface

Post by rkulagow » Sun Feb 16, 2014 7:07 pm

The format of the /status call has been updated.

maxHeadends is now maxLineups.
The returned lineups include a "uri" field which the client should use to download the lineup information.

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: API 20131021 will implement a REST interface

Post by rkulagow » Sun Feb 23, 2014 8:36 am

Update example for retrieving program IDs. The response is a flat file, with each JSON response per-line.

iShBuu
Posts: 3
Joined: Mon Feb 04, 2013 1:47 pm

Re: API 20131021 will implement a REST interface

Post by iShBuu » Mon Apr 07, 2014 11:53 am

is the beta server down? I'm trying every method i have against it using REST, but I just keep getting 404's back. Is there some test URL to use with development like with the old /request.php form?
@iShBuu

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: API 20131021 will implement a REST interface

Post by rkulagow » Mon Apr 07, 2014 12:09 pm

iShBuu wrote:is the beta server down? I'm trying every method i have against it using REST, but I just keep getting 404's back. Is there some test URL to use with development like with the old /request.php form?
Try using https://json.schedulesdirect.org/20131021/

as the baseURL.

I've been testing using POSTman (chrome app) and the MythTV client at https://github.com/SchedulesDirect/mfdb-json

I've probably forgotten to update the example to include the pointer to the new URL.

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: API 20131021 will implement a REST interface

Post by rkulagow » Wed Apr 16, 2014 11:51 am

The HTTP response header will now include information on which server processed the request:

Schedulesdirect-Serverid: AWS-SD-web.1

cwchapma
Posts: 42
Joined: Fri Mar 29, 2013 8:32 am

Re: API 20131021 will implement a REST interface

Post by cwchapma » Wed Apr 30, 2014 9:21 am

When I try to get a token, I send:

Code: Select all

{
  "username": "cwchapma"
  "password": "sha1hex"
}
but keep getting:

Code: Select all

{
    "response": "INVALID_JSON",
    "code": 1001,
    "serverID": "AWS-SD-web.1",
    "message": "Unable to decode JSON",
    "datetime": "2014-04-30T14:49:13Z"
}
I'm assuming the spots you give the format as

Code: Select all

{"username":"rkulagow@rocketmail.com", "password":"{sha1hex"}
the '{' s are a typo?

Any ideas what the problem is. I'm using Postman in chrome (screenshot attached)
Attachments
sd-token-postman.PNG
sd-token-postman.PNG (105.95 KiB) Viewed 19006 times

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: API 20131021 will implement a REST interface

Post by rkulagow » Wed Apr 30, 2014 10:35 am

cwchapma wrote:When I try to get a token, I send:

Code: Select all

{
  "username": "cwchapma"
  "password": "sha1hex"
}
I've updated the example. The sha1hex must be the actual sha-1 hex of whatever your password is.

In the MythTV php grabber, I use:

Code: Select all

$passwordHash = sha1($userPassword);

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: API 20131021 will implement a REST interface

Post by rkulagow » Wed Apr 30, 2014 10:39 am

I've turned up some logging server-side, so if you're still having issues let me know and I'll PM you what I'm seeing at the server.

Post Reply