root/trunk/JsonAPI.txt @ 42

= API =

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

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

[[TOC]]

== Users and Roles ==

=== Create a New Role ===

{{{

{
    "request": "createrole",
    "username": <role creator's username>,
    "password": <role creator's password>,
    "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>,
    "password": <role editor's password>,
    "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>,
    "password": <role editor's password>,
    "rolename": <name> 
}


}}}

=== List all Roles ===

{{{

{
    "request": "listroles",
    "username": <requestor's username>,
    "password": <requestor's password>,
}

}}}

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

{{{

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

}}}

=== Create a New User ===

{{{

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


}}}

=== Edit an Existing User ===

{{{

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


}}}

=== Remove an Existing User ===

{{{

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


}}}

=== Retrieve an User's Details ==

{{{

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


}}}


=== List All Users ===

{{{

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


}}}


== Files and Playlists ==

=== Register an Audio File ===

{{{

{
    "request": "registerfile",
    "username": <username>,
    "password": <password>,
    "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>
    }
}

}}}

=== Get an Audio File ===

{{{

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

}}}

=== Search for an Audio File ===

{{{
{
    "request": "searchfiles",
    "username": <username>,
    "password": <password>,
    "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>
    }
}

}}}

=== Edit an Audio File ===

{{{
{
    "request": "editfile",
    "username": <username>,
    "password": <password>,
    "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>,
    "password": <password>,
    "mediafileid": <id of the media file to be deregistered>
}

}}}


=== Create a New Playlist ===

{{{

{
    "request": "createplaylist",
    "username": <username>,
    "password": <password>,
    "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>,
    "password": <password>,
    "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>
            ]
    }
}

}}}

=== Remove an Existing Playlist ===

{{{

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

}}}


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

{{{

{   
    "request": "addfilestoplaylist",
    "username": <username>,
    "password": <password>,
    "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>,
    "password": <password>,
    "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>,
    "password": <password>,
    "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>,
    "password": <password>,
    "user": <username or null>
}


}}}


== Time Slots ==

=== Reserve a Timeslot ===

{{{

{
    "request": "reservetimeslot",
    "username": <username>,
    "password": <password>,
    "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>,
    "password": <password>,
    "timeslotid": <id of the timeslot to be removed>
}


}}}

=== Edit a Timeslot ===

{{{

{
    "request": "edittimeslot",
    "username": <username>,
    "password": <password>,
    "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>,
    "password": <password>,
    "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>,
    "password": <password>
}

}}}

=== Test Slot ===

{{{

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



}}}


== Archive/Podcasts/Netcasts ==

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

{
    "request": "listnetcasts",
    "username": <username>,
    "password": <password>,
    "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$