JsonAPI.txt

= API =

 * before the definition of a playlist, files must be registered

 * when editing, leaving fields to null means that fields are left untouched


== Logging in and out ==

=== Log in ===

{
	"request": "login",
	"username": <username>,
	"password": <password>
}

The response contains a 'sessionid' key, whose value is to be used on subsequent requests

=== Log out ===

{
	"request": "logout",
	"username": <session ID>,
	"sessionid": <password>
}


== Users and Roles ==

=== Create a New Role ===



{
	"request": "createrole",
	"username": <role creator's username>,
	"sessionid": <role creator's session ID>,
	"role" : {
		"rolename": <name>,
		"canManageRoles": (true|false),  #true if the user can create/edit/delete roles
		"canManageUsers": (true|false),  #true if the user can create/edit/delete users
		"canManageAllPlaylists": (true|false),  #true if the user can create/edit/delete all playlists
		"canRegisterFiles": (true|false), #true if the user can register local files
		"canManageRegisteredFiles": (true|false), #true if the user can manage registered files' data (i.e. change, delete)
		"canManageTimetable": (true|false),  #true if the user can edit/delete the beginning and ending time of scheduled slots
		"fixedSlotTimes": (true|false), #true if the fixedSlotTimesList field has to be considered
		"fixedSlotTimesList": <array of fixed slot times, in minutes>, #if fixedSlotTime is true, then this is the list of the allowed length for the timeslots for this user
		"changeTimeBeforeTransmission": <number of minutes before the beginning of the transmission in which the user is permitted to change the beginning time>, # -1 for unlimited
		"canCreateTestSlot": (true|false) #true if the user is permitted to create a testing mountpoint
	}
}





=== Edit an Existing Role ===



{
	"request": "editrole",
	"username": <role editor's username>,
	"sessionid": <role editor's session ID>,
	"role" : {
		"rolename": <name>, #mandatory
		"canManageRoles": (true|false),  #true if the user can create/edit/delete roles
		"canManageUsers": (true|false),  #true if the user can create/edit/delete users
		"canManageAllPlaylists": (true|false),  #true if the user can create/edit/delete all playlists
		"canRegisterFiles": (true|false), #true if the user can register local files
		"canManageRegisteredFiles": (true|false), #true if the user can manage registered files' data (i.e. change, delete)
		"canManageTimetable": (true|false),  #true if the user can edit/delete the beginning and ending time of scheduled slots
		"fixedSlotTimes": (true|false), #true if the fixedSlotTimesList field has to be considered
		"fixedSlotTimesList": <array of fixed slot times, in minutes>, #if fixedSlotTime is true, then this is the list of the allowed length for the timeslots for this user
		"changeTimeBeforeTransmission": <number of minutes before the beginning of the transmission in which the user is permitted to change the beginning time>, # -1 for unlimited
		"canCreateTestSlot": (true|false) #true if the user is permitted to create a testing mountpoint
	}
}




=== Remove an Existing Role ===



{
	"request": "removerole",
	"username": <role editor's username>,
	"sessionid": <role editor's session ID>,
	"rolename": <name> 
}




=== List all Roles ===



{
	"request": "listroles",
	"username": <requestor's username>,
	"sessionid": <requestor's session ID>,
}



=== Get an Existing Role's details ===



{
	"request": "getrole",
	"username": <requestor's username>,
	"sessionid": <requestor's session ID>,
	"rolename": <requested role's name> 
}



=== Create a New User ===



{
	"request":"createuser",
	"username": <creator's username>,
	"sessionid": <session ID>,
	"user" : {
		"name": <username>,
		"password": <password>,
		"displayname": <name to be displayed>,
		"email": <user's email address>,
		"rolename": <existing role name>
	}
}




=== Edit an Existing User ===



{
	"request":"edituser",
	"username": <editor's username>,
	"sessionid": <session ID>,
	"user" : {
		"name": <name>,
		"password": <password>, 
		"displayname": <name to be displayed>,
		"email": <user's email address>,
		"rolename": <existing role name>
	}
}




=== Remove an Existing User ===



{
	"request": "removeuser",
	"username": <user editor's username>,
	"sessionid": <user editor's session ID>,
	"name": <username of the user to be removed> 
}




=== Retrieve an User's Details ==



{
	"request": "getuser",
	"username": <requestor's username>,
	"sessionid": <requestor's session ID>
	"name": <user name of the user to be retrieved>
}





=== List All Users ===



{
	"request":"listusers",
	"username": <username>,
	"sessionid": <session ID>,
}





== Files and Playlists ==

=== Register an Audio File ===



{
	"request": "registerfile",
	"username": <username>,
	"sessionid": <session ID>,
	"mediafile": {
		"path": <local path of the file>,
		"title": <title of the track>,
		"author": <author of the track>,
		"album": <album>,
		"genre": <genre>,
		"year": <year of pubblication>,
		"comment": <comment>,
		"license": <license of the file>,
		"tags": <tags>
	}
}



== Scan an existing file for ID3 tags ==

{
	"request": "scanfile",
	"username": <username>,
	"sessionid": <session ID>,
	"path": <path of the media file>
}


=== Get an Audio File ===



{
	"request": "getfile",
	"username": <username>,
	"sessionid": <session ID>,
	"mediafileid": <id of the media file>
}



=== Search for an Audio File ===


{
	"request": "searchfiles",
	"username": <username>,
	"sessionid": <session ID>,
	"mediafile": {
		"id": <id of the file>,
		"path": <partial or complete local path of the file>,
		"title": <partial or complete title of the track>,
		"author": <partial or complete author of the track>,
		"album": <partial or complete album>,
		"genre": <partial or complete genre>,
		"year": <year of pubblication>,
		"comment": <partial or complete comment>,
		"license": <partial or complete license of the file>,
		"tags": <one or more tags>
	}
}

== Search on all fields ==

{
	"request": "fullsearchfiles",
	"username": <username>,
	"sessionid": <session ID>,
	"q": <search term>
}


=== Edit an Audio File ===


{
	"request": "editfile",
	"username": <username>,
	"sessionid": <session ID>,
	"mediafile": {
		"id": <id of the file>,
		"path": <new local path of the file or null to leave unchanged>,
		"title": <new title of the track or null to leave unchanged>,
		"author": <new author of the track or null to leave unchanged>,
		"album": <new album or null to leave unchanged>,
		"genre": <new genre or null to leave unchanged>,
		"year": <new year of pubblication or null to leave unchanged>,
		"comment": <new comment or null to leave unchanged>,
		"license": <new license of the file or null to leave unchanged>,
		"tags": <new tags or null to leave unchanged>
	}
}




=== Unregister an Audio File ===



{
	"request": "unregisterfile",
	"username": <username>,
	"sessionid": <session ID>,
	"mediafileid": <id of the media file to be deregistered>
}




=== Create a New Playlist ===



{
	"request": "createplaylist",
	"username": <username>,
	"sessionid": <session ID>,
	"playlist": {
			"title": <a name for the playlist>,
			"description": <a description of the playlist>,
			"comment": <comment>,
			"tags": <tags>,
			"private": (true|false), #true if this playlist can be viewed only by the owner (or with the canManageAllPlaylists role attribute)
			"random": (true|false), #true if this playlist will be played in random order
			"viewers": [ # a list of usernames of other users that can watch and play this playlist
				<username>,
				<username>
			]
			"owners": [ # a list of usernames of other users that can manage this playlist
				<username>,
				<username>
			]
	}
}




=== Edit an Existing Playlist ===



{
	"request": "editplaylist",
	"username": <username>,
	"sessionid": <session ID>,
	"playlist": {
			"id": <the id of the existing playlist that we are editing>,
			"title": <a new name for the playlist or null to leave unchanged>,
			"description": <a new description of the playlist or null to leave unchanged>,
			"comment": <a new comment or null to leave unchanged>,
			"tags": <new tags or null to leave unchanged>,
			"private": (true|false), #true if this playlist can be viewed only by the owner (or with the canManageAllPlaylists role attribute)
			"random": (true|false), #true if this playlist will be played in random order
			"viewers": [ # a list of usernames of other users that can watch and play this playlist, or null to leave unchanged
				<username>,
				<username>
			]
			"owners": [ # a list of usernames of other users that can manage this playlist, or null to leave unchanged
				<username>,
				<username>
			]
	}
}


=== Get a Playlist ===

{
	"request": "getplaylist",
	"username": <username>,
	"sessionid": <session ID>,
	"playlistid": <id of the playlist to be retrieved>
}



=== Remove an Existing Playlist ===



{
	"request": "removeplaylist",
	"username": <username>,
	"sessionid": <session ID>,
	"playlistid": <id of the playlist to be removed>
}




=== Add Files to an Existing Playlist ===



{	
	"request": "addfilestoplaylist",
	"username": <username>,
	"sessionid": <session ID>,
	"playlistid": <id of an existing playlist>,
	"mediafileidlist": [ #ordered list of file ids
		<id of a registered file>,
		<id of a registered file>,
		...
	]
}




=== Remove Files from an Existing Playlist ===



{	
	"request": "removefilesfromplaylist",
	"username": <username>,
	"sessionid": <session ID>,
	"playlistid": <id of an existing playlist>,
	"mediafilepositionlist": [ # list of mediafile positions
		<position of a file in the playlist>,
		<position of a file in the playlist>,
		...
	]
}




=== Change Position of file in an Existing Playlist ===



{	
	"request": "movefilesinplaylist",
	"username": <username>,
	"sessionid": <session ID>,
	"playlistid": <id of an existing playlist>,
	"oldmediafileposition": <old position of a file in the playlist>,
	"newmediafileposition": <new position of a file in the playlist> 
		#if there is already a file present, then the old one is moved one position further




=== List Users' Playlists ===

List of playlists in which the user is owner or viewer 

 * users with a role with the canManageAllPlaylists flag set to true are co-owners of all playlists
 * an owner of a playlist is also viewer 



{
	"request": "listuserplaylists",
	"username": <username>,
	"sessionid": <session ID>,
	"user": <username or null>
}





== Time Slots ==

=== Reserve a Timeslot ===



{
	"request": "reservetimeslot",
	"username": <username>,
	"sessionid": <session ID>,
	"timeslot": {
		"title": <title of the transmission>,
		"description": <description of the transmission>,
		"fallbackplaylist": <an existing playlist, to be used as fallback>,
		"slottype": <type of slot to be created>,
		"beginningtime": {
			"year": <year>,
			"month": <month>,
			"day": <day>,
			"hour": <hour>,
			"minute": <minute>
		},
		"duration": <duration of the timeslot in minutes>,
		"slotparams": {
			<slot-specific parameters>
		},
		"comment": <a comment>,
		"tags": <tags>
	}
}




=== Unreserve a Timeslot ===



{
	"request": "unreservetimeslot",
	"username": <username>,
	"sessionid": <session ID>,
	"timeslotid": <id of the timeslot to be removed>
}




=== Edit a Timeslot ===



{
	"request": "edittimeslot",
	"username": <username>,
	"sessionid": <session ID>,
	"timeslot": {
		"id": <id of the timeslot to be edited>,
		"title": <title of the transmission>,
		"description": <description of the transmission>,
		"fallbackplaylist": <an existing playlist, to be used as fallback>,
		"slottype": <type of slot to be created>,
		"beginningtime": {
			"year": <year>,
			"month": <month>,
			"day": <day>,
			"hour": <hour>,
			"minute": <minute>
		},
		"duration": <duration of the timeslot in minutes>,
		"slotparams": {
			<slot-specific parameters>
		},
		"comment": <a comment>,
		"tags": <tags>
	}
}




=== List Timeslots ===



{
	"request": "listtimeslots",
	"username": <username>,
	"sessionid": <session ID>,
	"timeslot": {
		"id": <id of the timeslot or null>,
		"title": <title of the transmission or null>,
		"description": <description of the transmission or null>,
		"tags": <null or tags>,
		"comment": <null or partial comment>,
		"creator": <user who reserved the timeslot, or null>,
		"from": { #or null
			"year": <year>,
			"month": <month>,
			"day": <day>,
			"hour": <hour>,
			"minute": <minute>
		},
		"to": { # or null
			"year": <year>,
			"month": <month>,
			"day": <day>,
			"hour": <hour>,
			"minute": <minute>
		}
	}
}




=== List Available Slot Types (for the timeslot.slottype field) ===



{
	"request": "listslottypes",
	"username": <username>,
	"sessionid": <session ID>
}

=== List Required parameter for a specified slot type ===

{
	"request": "getslotreqparameters",
	"username": <username>,
	"sessionid": <session ID>,
	"slottype": <slot type name>
}


=== Test Slot ===



{
	"request": "createtestslot",
	"username": <username>,
	"sessionid": <session ID>,
	"testslot": {
		"slottype": <type of slot to be created>,
		"duration": <duration of the testslot in minutes>,
		"slotparams": {
			<slot-specific parameters>
		}
	}
}






== Archive/Podcasts/Netcasts ==

NOT YET IMPLEMENTED

=== List/Search Archive/Podcasts/Netcasts ===

{
	"request": "listnetcasts",
	"username": <username>,
	"sessionid": <session ID>,
	"netcast": {
		"user": <owner of the transmission, or null>
		"title": <complete or partial title of the transmission, or null>
		"description": <complete or partial description of the transmission>
		"tags": <zero or more tags>
		"slottype": <type of slot>,
		"from": { # or null
			"year": <year>,
			"month": <month>,
			"day": <day>,
			"hour": <hour>,
			"minute": <minute>
		},
		"to": { #or null
			"year": <year>,
			"month": <month>,
			"day": <day>,
			"hour": <hour>,
			"minute": <minute>
		}
		"limit": <maximum number of transmissions to display, or null>
	}
}

		
== Responses ==



{
	"response": ("ok" | "notallowed" | "dontexists" | "alreadyexists" | "servererror" | "error" | "requesterror", "notimplemented"),
	"responsen": (0 | 101 | 201 | 202 | 301 | 401 | 501 | 601),
	"requested": <the requested action>,
	"warning": <warning message(s) or null>,
	"description": <textual description>,
	<the response follows>
}




$Id$