= Broadcast Extraction Service (BES) API and usage =

BES is a REST webservice with a single method which is called with a GET request like
{{{
http://iapetus:9311/bes/rest/bes/getobjectstatus?programpid=http://www.statsbiblioteket.dk/doms/shard/uuid:066d8172-7585-43bf-bf65-4aacb6a5f378
}}}
It responds as appropriate by
 i. Starting a new transcoding process for the requested broadcast,
 i. Reporting status information on an in-progress transcoding, or
 i. Returning a reference to a file created by a completed transcoding process.

For each shard-uuid requested, corresponding to a single TV or Radio broadcast, BES creates two files - a media file <uuid>.flv or <uuid>.mp3, and a lock file <uuid>.lck. On completion of transcoding, the .lck file is deleted. The status returned by BES is therefore determined as follows
 i. If neither file exists, a new transcoding is started and the status {{{STARTING}}} is returned.
 i. If the .lck file exists, status {{{STARTED}}} is returned along with a reference to the unfinished media file if it has been created and an estimate of the completion percentage.
 i. If the media file exists but the .lck file does not exist, the status {{{DONE}}} is returned along with a reference to the media file.

On reload of the web-application, any .lck files are deleted along with their corresponding media files, thus cleaning up any partially completed transcodings.