root/trunk/JsonAPI.txt @ 42

Revision 42, 13.7 KB (checked in by clauz, 4 years ago)

adding playlist randomization plus small changes

  • Property svn:keywords set to Id
Line 
1= API =
2
3 * before the definition of a playlist, files must be registered
4
5 * when editing, leaving fields to null means that fields are left untouched
6
7[[TOC]]
8
9== Users and Roles ==
10
11=== Create a New Role ===
12
13{{{
14
15{
16    "request": "createrole",
17    "username": <role creator's username>,
18    "password": <role creator's password>,
19    "role" : {
20        "rolename": <name>,
21        "canManageRoles": (true|false),  #true if the user can create/edit/delete roles
22        "canManageUsers": (true|false),  #true if the user can create/edit/delete users
23        "canManageAllPlaylists": (true|false),  #true if the user can create/edit/delete all playlists
24        "canRegisterFiles": (true|false), #true if the user can register local files
25        "canManageRegisteredFiles": (true|false), #true if the user can manage registered files' data (i.e. change, delete)
26        "canManageTimetable": (true|false),  #true if the user can edit/delete the beginning and ending time of scheduled slots
27        "fixedSlotTimes": (true|false), #true if the fixedSlotTimesList field has to be considered
28        "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
29        "changeTimeBeforeTransmission": <number of minutes before the beginning of the transmission in which the user is permitted to change the beginning time>, # -1 for unlimited
30        "canCreateTestSlot": (true|false) #true if the user is permitted to create a testing mountpoint
31    }
32}
33
34
35
36}}}
37
38=== Edit an Existing Role ===
39
40{{{
41
42{
43    "request": "editrole",
44    "username": <role editor's username>,
45    "password": <role editor's password>,
46    "role" : {
47        "rolename": <name>, #mandatory
48        "canManageRoles": (true|false),  #true if the user can create/edit/delete roles
49        "canManageUsers": (true|false),  #true if the user can create/edit/delete users
50        "canManageAllPlaylists": (true|false),  #true if the user can create/edit/delete all playlists
51        "canRegisterFiles": (true|false), #true if the user can register local files
52        "canManageRegisteredFiles": (true|false), #true if the user can manage registered files' data (i.e. change, delete)
53        "canManageTimetable": (true|false),  #true if the user can edit/delete the beginning and ending time of scheduled slots
54        "fixedSlotTimes": (true|false), #true if the fixedSlotTimesList field has to be considered
55        "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
56        "changeTimeBeforeTransmission": <number of minutes before the beginning of the transmission in which the user is permitted to change the beginning time>, # -1 for unlimited
57        "canCreateTestSlot": (true|false) #true if the user is permitted to create a testing mountpoint
58    }
59}
60
61
62}}}
63
64=== Remove an Existing Role ===
65
66{{{
67
68{
69    "request": "removerole",
70    "username": <role editor's username>,
71    "password": <role editor's password>,
72    "rolename": <name>
73}
74
75
76}}}
77
78=== List all Roles ===
79
80{{{
81
82{
83    "request": "listroles",
84    "username": <requestor's username>,
85    "password": <requestor's password>,
86}
87
88}}}
89
90=== Get an Existing Role's details ===
91
92{{{
93
94{
95    "request": "getrole",
96    "username": <requestor's username>,
97    "password": <requestor's password>,
98    "rolename": <requested role's name>
99}
100
101}}}
102
103=== Create a New User ===
104
105{{{
106
107{
108    "request":"createuser",
109    "username": <creator's username>,
110    "password": <creator's password>,
111    "user" : {
112        "name": <username>,
113        "password": <password>,
114        "displayname": <name to be displayed>,
115        "rolename": <existing role name>
116    }
117}
118
119
120}}}
121
122=== Edit an Existing User ===
123
124{{{
125
126{
127    "request":"edituser",
128    "username": <editor's username>,
129    "password": <editor's password>,
130    "user" : {
131        "name": <name>,
132        "password": <password>,
133        "displayname": <name to be displayed>,
134        "rolename": <existing role name>
135    }
136}
137
138
139}}}
140
141=== Remove an Existing User ===
142
143{{{
144
145{
146    "request": "removeuser",
147    "username": <user editor's username>,
148    "password": <user editor's password>,
149    "name": <username of the user to be removed>
150}
151
152
153}}}
154
155=== Retrieve an User's Details ==
156
157{{{
158
159{
160    "request": "getuser",
161    "username": <requestor's username>,
162    "password": <requestor's password>
163    "name": <user name of the user to be retrieved>
164}
165
166
167}}}
168
169
170=== List All Users ===
171
172{{{
173
174{
175    "request":"listusers",
176    "username": <username>,
177    "password": <password>,
178}
179
180
181}}}
182
183
184== Files and Playlists ==
185
186=== Register an Audio File ===
187
188{{{
189
190{
191    "request": "registerfile",
192    "username": <username>,
193    "password": <password>,
194    "mediafile": {
195        "path": <local path of the file>,
196        "title": <title of the track>,
197        "author": <author of the track>,
198        "album": <album>,
199        "genre": <genre>,
200        "year": <year of pubblication>,
201        "comment": <comment>,
202        "license": <license of the file>,
203        "tags": <tags>
204    }
205}
206
207}}}
208
209=== Get an Audio File ===
210
211{{{
212
213{
214    "request": "getfile",
215    "username": <username>,
216    "password": <password>,
217    "mediafileid": <id of the media file>
218}
219
220}}}
221
222=== Search for an Audio File ===
223
224{{{
225{
226    "request": "searchfiles",
227    "username": <username>,
228    "password": <password>,
229    "mediafile": {
230        "id": <id of the file>,
231        "path": <partial or complete local path of the file>,
232        "title": <partial or complete title of the track>,
233        "author": <partial or complete author of the track>,
234        "album": <partial or complete album>,
235        "genre": <partial or complete genre>,
236        "year": <year of pubblication>,
237        "comment": <partial or complete comment>,
238        "license": <partial or complete license of the file>,
239        "tags": <one or more tags>
240    }
241}
242
243}}}
244
245=== Edit an Audio File ===
246
247{{{
248{
249    "request": "editfile",
250    "username": <username>,
251    "password": <password>,
252    "mediafile": {
253        "id": <id of the file>,
254        "path": <new local path of the file or null to leave unchanged>,
255        "title": <new title of the track or null to leave unchanged>,
256        "author": <new author of the track or null to leave unchanged>,
257        "album": <new album or null to leave unchanged>,
258        "genre": <new genre or null to leave unchanged>,
259        "year": <new year of pubblication or null to leave unchanged>,
260        "comment": <new comment or null to leave unchanged>,
261        "license": <new license of the file or null to leave unchanged>,
262        "tags": <new tags or null to leave unchanged>
263    }
264}
265
266
267}}}
268
269=== Unregister an Audio File ===
270
271{{{
272
273{
274    "request": "unregisterfile",
275    "username": <username>,
276    "password": <password>,
277    "mediafileid": <id of the media file to be deregistered>
278}
279
280}}}
281
282
283=== Create a New Playlist ===
284
285{{{
286
287{
288    "request": "createplaylist",
289    "username": <username>,
290    "password": <password>,
291    "playlist": {
292            "title": <a name for the playlist>,
293            "description": <a description of the playlist>,
294            "comment": <comment>,
295            "tags": <tags>,
296            "private": (true|false), #true if this playlist can be viewed only by the owner (or with the canManageAllPlaylists role attribute)
297            "random": (true|false), #true if this playlist will be played in random order
298            "viewers": [ # a list of usernames of other users that can watch and play this playlist
299                <username>,
300                <username>
301            ]
302            "owners": [ # a list of usernames of other users that can manage this playlist
303                <username>,
304                <username>
305            ]
306    }
307}
308
309
310}}}
311
312=== Edit an Existing Playlist ===
313
314{{{
315
316{
317    "request": "editplaylist",
318    "username": <username>,
319    "password": <password>,
320    "playlist": {
321            "id": <the id of the existing playlist that we are editing>,
322            "title": <a new name for the playlist or null to leave unchanged>,
323            "description": <a new description of the playlist or null to leave unchanged>,
324            "comment": <a new comment or null to leave unchanged>,
325            "tags": <new tags or null to leave unchanged>,
326            "private": (true|false), #true if this playlist can be viewed only by the owner (or with the canManageAllPlaylists role attribute)
327            "random": (true|false), #true if this playlist will be played in random order
328            "viewers": [ # a list of usernames of other users that can watch and play this playlist, or null to leave unchanged
329                <username>,
330                <username>
331            ]
332            "owners": [ # a list of usernames of other users that can manage this playlist, or null to leave unchanged
333                <username>,
334                <username>
335            ]
336    }
337}
338
339}}}
340
341=== Remove an Existing Playlist ===
342
343{{{
344
345{
346    "request": "removeplaylist",
347    "username": <username>,
348    "password": <password>,
349    "playlistid": <id of the playlist to be removed>
350}
351
352}}}
353
354
355=== Add Files to an Existing Playlist ===
356
357{{{
358
359{   
360    "request": "addfilestoplaylist",
361    "username": <username>,
362    "password": <password>,
363    "playlistid": <id of an existing playlist>,
364    "mediafileidlist": [ #ordered list of file ids
365        <id of a registered file>,
366        <id of a registered file>,
367        ...
368    ]
369}
370
371}}}
372
373
374=== Remove Files from an Existing Playlist ===
375
376{{{
377
378{   
379    "request": "removefilesfromplaylist",
380    "username": <username>,
381    "password": <password>,
382    "playlistid": <id of an existing playlist>,
383    "mediafilepositionlist": [ # list of mediafile positions
384        <position of a file in the playlist>,
385        <position of a file in the playlist>,
386        ...
387    ]
388}
389
390}}}
391
392
393=== Change Position of file in an Existing Playlist ===
394
395{{{
396
397{   
398    "request": "movefilesinplaylist",
399    "username": <username>,
400    "password": <password>,
401    "playlistid": <id of an existing playlist>,
402    "oldmediafileposition": <old position of a file in the playlist>,
403    "newmediafileposition": <new position of a file in the playlist>
404        #if there is already a file present, then the old one is moved one position further
405
406}}}
407
408
409=== List Users' Playlists ===
410
411List of playlists in which the user is owner or viewer
412
413 * users with a role with the canManageAllPlaylists flag set to true are co-owners of all playlists
414 * an owner of a playlist is also viewer
415
416{{{
417
418{
419    "request": "listuserplaylists",
420    "username": <username>,
421    "password": <password>,
422    "user": <username or null>
423}
424
425
426}}}
427
428
429== Time Slots ==
430
431=== Reserve a Timeslot ===
432
433{{{
434
435{
436    "request": "reservetimeslot",
437    "username": <username>,
438    "password": <password>,
439    "timeslot": {
440        "title": <title of the transmission>,
441        "description": <description of the transmission>,
442        "fallbackplaylist": <an existing playlist, to be used as fallback>,
443        "slottype": <type of slot to be created>,
444        "beginningtime": {
445            "year": <year>,
446            "month": <month>,
447            "day": <day>,
448            "hour": <hour>,
449            "minute": <minute>
450        },
451        "duration": <duration of the timeslot in minutes>,
452        "slotparams": {
453            <slot-specific parameters>
454        },
455        "comment": <a comment>,
456        "tags": <tags>
457    }
458}
459
460
461}}}
462
463=== Unreserve a Timeslot ===
464
465{{{
466
467{
468    "request": "unreservetimeslot",
469    "username": <username>,
470    "password": <password>,
471    "timeslotid": <id of the timeslot to be removed>
472}
473
474
475}}}
476
477=== Edit a Timeslot ===
478
479{{{
480
481{
482    "request": "edittimeslot",
483    "username": <username>,
484    "password": <password>,
485    "timeslot": {
486        "id": <id of the timeslot to be edited>,
487        "title": <title of the transmission>,
488        "description": <description of the transmission>,
489        "fallbackplaylist": <an existing playlist, to be used as fallback>,
490        "slottype": <type of slot to be created>,
491        "beginningtime": {
492            "year": <year>,
493            "month": <month>,
494            "day": <day>,
495            "hour": <hour>,
496            "minute": <minute>
497        },
498        "duration": <duration of the timeslot in minutes>,
499        "slotparams": {
500            <slot-specific parameters>
501        },
502        "comment": <a comment>,
503        "tags": <tags>
504    }
505}
506
507
508}}}
509
510=== List Timeslots ===
511
512{{{
513
514{
515    "request": "listtimeslots",
516    "username": <username>,
517    "password": <password>,
518    "timeslot": {
519        "id": <id of the timeslot or null>,
520        "title": <title of the transmission or null>,
521        "description": <description of the transmission or null>,
522        "tags": <null or tags>,
523        "comment": <null or partial comment>,
524        "creator": <user who reserved the timeslot, or null>,
525        "from": { #or null
526            "year": <year>,
527            "month": <month>,
528            "day": <day>,
529            "hour": <hour>,
530            "minute": <minute>
531        },
532        "to": { # or null
533            "year": <year>,
534            "month": <month>,
535            "day": <day>,
536            "hour": <hour>,
537            "minute": <minute>
538        }
539    }
540}
541
542
543}}}
544
545=== List Available Slot Types (for the timeslot.slottype field) ===
546
547{{{
548
549{
550    "request": "listslottypes",
551    "username": <username>,
552    "password": <password>
553}
554
555}}}
556
557=== Test Slot ===
558
559{{{
560
561{
562    "request": "createtestslot",
563    "username": <username>,
564    "password": <password>,
565    "testslot": {
566        "slottype": <type of slot to be created>,
567        "duration": <duration of the testslot in minutes>,
568        "slotparams": {
569            <slot-specific parameters>
570        }
571    }
572}
573
574
575
576}}}
577
578
579== Archive/Podcasts/Netcasts ==
580
581=== List/Search Archive/Podcasts/Netcasts ===
582
583{
584    "request": "listnetcasts",
585    "username": <username>,
586    "password": <password>,
587    "netcast": {
588        "user": <owner of the transmission, or null>
589        "title": <complete or partial title of the transmission, or null>
590        "description": <complete or partial description of the transmission>
591        "tags": <zero or more tags>
592        "slottype": <type of slot>,
593        "from": { # or null
594            "year": <year>,
595            "month": <month>,
596            "day": <day>,
597            "hour": <hour>,
598            "minute": <minute>
599        },
600        "to": { #or null
601            "year": <year>,
602            "month": <month>,
603            "day": <day>,
604            "hour": <hour>,
605            "minute": <minute>
606        }
607        "limit": <maximum number of transmissions to display, or null>
608    }
609}
610
611       
612== Responses ==
613
614{{{
615
616{
617    "response": ("ok" | "notallowed" | "dontexists" | "alreadyexists" | "servererror" | "error" | "requesterror", "notimplemented"),
618    "responsen": (0 | 101 | 201 | 202 | 301 | 401 | 501 | 601),
619    "requested": <the requested action>,
620    "warning": <warning message(s) or null>,
621    "description": <textual description>,
622    <the response follows>
623}
624
625}}}
626
627
628$Id$
629
Note: See TracBrowser for help on using the browser.