RocketBeans API
The RocketBeans API provides information about Rocket Beans TV
Authorization
The RocketBeans API uses the WSSE UsernameToken Algorithm
WSSE is a family of open security specifications for web services, specifically SOAP web services. However, the UsernameToken (PDF) algorithm is not SOAP-specific, it can be easily adapted to work within the HTTP authentication framework.
The algorithm itself works like this:
-
Start with 2 pieces of information: Key and Secret.
-
Create a Nonce, which is a cryptographically random string. This is harder than it sounds; if an attacker can guess your next nonce, they can still attempt a replay attack. Most cryptography libraries have routines to generate decent nonces, the specifics of doing which are beyond the scope of this documentation.
-
Create a CreationTimestamp of the current time, in W3DTF format.
-
Create a PasswordDigest that is SHA1 hashed and Base64 encoded:
PasswordDigest = Base64 \ (SHA1 (Nonce + CreationTimestamp + Secret))
An example will help make this clearer:
-
Let’s say Bob’s Key is
"bob"
, and his Secret is"taadtaadpstcsm"
. -
Bob creates a Nonce,
"d36e316282959a9ed4c89851497a717f"
. -
Bob created this nonce at
"2003-12-15T14:43:07Z"
, so that’s the CreationTimestamp. -
Bob’s PasswordDigest is
Base64 \ (SHA1 ("d36e316282959a9ed4c89851497a717f" + "2003-12-15T14:43:07Z" + "taadtaadpstcsm"))
, which is"quR/EWLAV4xLf9Zqyw4pDmfV90Y="
. Most languages have built-in libraries to create SHA-1 hashes and to encode strings in Base64 format.
Now let’s see how this algorithm fits into the HTTP authentication framework:
The RocketBeans API is at api.rocketmgmt.de, and has a /podcast
endpoint. Bob want to get the Podcasts, by sending an HTTP GET request:
GET /podcast HTTP/1.1
Host: api.rocketmgmt.de
Authorization: WSSE profile="UsernameToken"
X-WSSE: UsernameToken Username="bob", PasswordDigest="quR/EWLAV4xLf9Zqyw4pDmfV9OY=", Nonce="d36e316282959a9ed4c89851497a717f", Created="2003-12-15T14:43:07Z"
Podcasts ¶
Podcast List ¶
GET PodcastsGET/podcast
Get a list of podcasts.
Example URI
200
Headers
Content-Type: text/html;charset=UTF-8
Body
{
"podcasts": [
{
"title": "Wasser & IPhones",
"description": "Folge 1",
"length": "3568",
"url": "http:\\/\\/cdn.rocketmgmt.de\\/mp3\\/almost_daily\\/almostdaily_e001.mp3",
"image": "http:\\/\\/cdn.rocketmgmt.de\\/images\\/app\\/almost_daily.jpg",
"filesize": "143"
}
]
}
Schema
{
"type": "object",
"properties": {
"podcasts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The Podcast Title."
},
"description": {
"type": "string",
"description": "The Podcast Description."
},
"length": {
"type": "string",
"description": "The Podcast Length in Seconds."
},
"url": {
"type": "string",
"description": "The URL to the Podcast."
},
"image": {
"type": "string",
"description": "The URL to the Podcast Image."
},
"filesize": {
"type": "string",
"description": "The Size of the Podcast in MB."
}
}
}
}
},
"$schema": "http://json-schema.org/draft-04/schema#"
}
Schedule ¶
Schedule List ¶
GET Schedule ListGET/schedule
Get the schedule of the current week as one list.
Example URI
200
Headers
Content-Type: text/html;charset=UTF-8
Body
{
"schedule": [
{
"id": 37663,
"title": "Knallhart Durchgenommen",
"topic": "Knallhart Durchgenommen: Dark Souls III",
"show": "Knallhart Durchgenommen",
"timeStart": "2016-04-22T22:00:00+02:00",
"timeEnd": "2016-04-23T00:09:17+02:00",
"length": 7757,
"type": "premiere",
"game": "Dark Souls III"
}
]
}
Schema
{
"type": "object",
"properties": {
"schedule": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The Show ID."
},
"title": {
"type": "string",
"description": "The Show Title"
},
"topic": {
"type": "string",
"description": "The Show Topic."
},
"show": {
"type": "string",
"description": "The kind of the Show."
},
"timeStart": {
"type": "string",
"description": "The start time of the Show."
},
"timeEnd": {
"type": "string",
"description": "The end time of the Show."
},
"length": {
"type": "number",
"description": "The Show Length in Seconds."
},
"type": {
"enum": [
"premiere",
"live"
],
"description": "The Show Type can be premiere, live or ."
},
"game": {
"type": "string",
"description": "The Game played in the Show."
}
}
}
}
},
"$schema": "http://json-schema.org/draft-04/schema#"
}
Schedule List ¶
GET Next X ShowsGET/schedule/next/{limit}
Get the the next x Shows starting from the current show.
Example URI
- limit
number
(required) Example: 5number of shows you receive
200
Headers
Content-Type: text/html;charset=UTF-8
Body
{
"schedule": [
{
"id": 37663,
"title": "Knallhart Durchgenommen",
"topic": "Knallhart Durchgenommen: Dark Souls III",
"show": "Knallhart Durchgenommen",
"timeStart": "2016-04-22T22:00:00+02:00",
"timeEnd": "2016-04-23T00:09:17+02:00",
"length": 7757,
"type": "premiere",
"game": "Dark Souls III"
}
]
}
Schema
{
"type": "object",
"properties": {
"schedule": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The Show ID."
},
"title": {
"type": "string",
"description": "The Show Title"
},
"topic": {
"type": "string",
"description": "The Show Topic."
},
"show": {
"type": "string",
"description": "The kind of the Show."
},
"timeStart": {
"type": "string",
"description": "The start time of the Show."
},
"timeEnd": {
"type": "string",
"description": "The end time of the Show."
},
"length": {
"type": "number",
"description": "The Show Length in Seconds."
},
"type": {
"enum": [
"premiere",
"live"
],
"description": "The Show Type can be premiere, live or ."
},
"game": {
"type": "string",
"description": "The Game played in the Show."
}
}
}
}
},
"$schema": "http://json-schema.org/draft-04/schema#"
}
Week Schedule ¶
GET Week ScheduleGET/schedule/weekdays
Get the schedule of the current week sorted by weekdays.
Example URI
200
Headers
Content-Type: text/html;charset=UTF-8
Body
{
"schedule": {
"18.04.2016": [
{
"id": 37663,
"title": "Knallhart Durchgenommen",
"topic": "Knallhart Durchgenommen: Dark Souls III",
"show": "Knallhart Durchgenommen",
"timeStart": "2016-04-22T22:00:00+02:00",
"timeEnd": "2016-04-23T00:09:17+02:00",
"length": 7757,
"type": "premiere",
"game": "Dark Souls III"
}
]
}
}
Schema
{
"type": "object",
"properties": {
"schedule": {
"type": "object",
"properties": {
"18.04.2016": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The Show ID."
},
"title": {
"type": "string",
"description": "The Show Title"
},
"topic": {
"type": "string",
"description": "The Show Topic."
},
"show": {
"type": "string",
"description": "The kind of the Show."
},
"timeStart": {
"type": "string",
"description": "The start time of the Show."
},
"timeEnd": {
"type": "string",
"description": "The end time of the Show."
},
"length": {
"type": "number",
"description": "The Show Length in Seconds."
},
"type": {
"enum": [
"premiere",
"live"
],
"description": "The Show Type can be premiere, live or ."
},
"game": {
"type": "string",
"description": "The Game played in the Show."
}
}
},
"description": "Date of the Weekday"
}
}
}
},
"$schema": "http://json-schema.org/draft-04/schema#"
}
Current Show ¶
GET current ShowGET/schedule/current
Get the show that is currently running.
Example URI
200
Headers
Content-Type: text/html;charset=UTF-8
Body
{
"id": 37663,
"title": "Knallhart Durchgenommen",
"topic": "Knallhart Durchgenommen: Dark Souls III",
"show": "Knallhart Durchgenommen",
"timeStart": "2016-04-22T22:00:00+02:00",
"timeEnd": "2016-04-23T00:09:17+02:00",
"length": 7757,
"type": "premiere",
"game": "Dark Souls III"
}
Schema
{
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The Show ID."
},
"title": {
"type": "string",
"description": "The Show Title"
},
"topic": {
"type": "string",
"description": "The Show Topic."
},
"show": {
"type": "string",
"description": "The kind of the Show."
},
"timeStart": {
"type": "string",
"description": "The start time of the Show."
},
"timeEnd": {
"type": "string",
"description": "The end time of the Show."
},
"length": {
"type": "number",
"description": "The Show Length in Seconds."
},
"type": {
"enum": [
"premiere",
"live"
],
"description": "The Show Type can be premiere, live or ."
},
"game": {
"type": "string",
"description": "The Game played in the Show."
}
},
"$schema": "http://json-schema.org/draft-04/schema#"
}