rotter-web-service Readme
=========================
This article describes the rotter-web-service API and uses the following
conventions: Code is presented in code blocks, mandatory input parameters are
enclosed in angle brackets "<" and ">" and optional input parameters are
enclosed in square brackets "[" and "]".

All input parameters can be either GET or POST variables. '''Unless otherwise
stated, times are UTC.'''

listservices.php:
-----------------
; Service Description: Lists the services that can be queried through the various AudioFile Web Services

; Input Parameters: none required
; [callback]: JavaScript function name

; Returned Output: A JSON list of services in the format:
```JSON
 {
 	"services":[
 		{
                         "title":"RTÉ Radio 1 FM",
                         "id":"radio1"
 		},
 		{
 			"title":"RTÉ 2fm",
 			"id":"2fm"
 		},
 		{
 			"title":"RTÉ lyric fm",
 			"id":"lyricfm"
 		},
 		...
 	]
 }
```

listfiles.php:
--------------
; Service Description: Lists all of the files for a given service on a given date.

; Input Parameters
; <service>: one of the ids returned by listservices.php
; <date>: in format "YYYY-MM-DD"

; Returned Output: A JSON list of files in the format:
```JSON
 {
 	"files":[
 		{
 			"title":"00:00:00",
 			"file":"2011-01-18-00-00-00-00.mp3",
 			"size":28802317
 		},
 		{
 			"title":"01:00:00",
 			"file":"2011-01-18-01-00-00-02.mp3",
 			"size":28803137
 		}
 	]
 }
```

'''Note:''' The title field in the returned JSON is adjusted for daylight saving time.

download.php:
-------------
; Service Description: Produce a single file for download from the specified service between the start and end times specified.

; Input Parameters
; <service>: one of the ids returned by listservices.php
; <start>: in format "YYYY-MM-DD-HH-mm-ss-hh", hh represents the hundredth of a second
; <end>: in format "YYYY-MM-DD-HH-mm-ss-hh"
; [format]: "mp2" or "mp3" - mp3 by default
; [file_title]: the title returned in the 'Content-Disposition: attachment; filename=' HTTP header (exclude the file suffix (i.e. don't include the '.mp2' - this is set automatically). If not provided, this defaults to 'output'

'''Note:''' The maximum difference between start and end times has been capped and tested at 24 hours.

'''Note:''' The start and end times can straddle day boundaries.

; Returned Output: A HTTP 200 response with Content-Type: audio/mpeg followed by the mpeg audio data.
;: If there is any problem, a HTTP 404 error will be generated.