From 6bd001a10abd5f3865a5822e8cb02c81c6eb4ebc Mon Sep 17 00:00:00 2001 From: rolux Date: Thu, 18 Dec 2014 20:16:41 +0000 Subject: [PATCH] update api docs --- pandora/archive/views.py | 255 ++++++++++++++++---------------------- pandora/event/views.py | 66 +++------- pandora/item/views.py | 1 + pandora/itemlist/views.py | 83 ++++++------- pandora/news/views.py | 86 +++++++------ pandora/place/views.py | 2 +- 6 files changed, 213 insertions(+), 280 deletions(-) diff --git a/pandora/archive/views.py b/pandora/archive/views.py index 1fadd415..0baaf397 100644 --- a/pandora/archive/views.py +++ b/pandora/archive/views.py @@ -44,28 +44,29 @@ actions.register(removeVolume, cache=False) @login_required_json def update(request, data): ''' - 2 steps: - send files - {volume: 'Videos', files: [{oshash:, path:, mtime:, ,,}]} - send info about changed/new files - {volume: 'Videos', info: {oshash: {...}]} + Undocumented + 2 steps: + send files + {volume: 'Videos', files: [{oshash:, path:, mtime:, ,,}]} + send info about changed/new files + {volume: 'Videos', info: {oshash: {...}]} - call volume/files first and fill in requested info after that + call volume/files first and fill in requested info after that - takes { - volume: '', - files: [ - {oshash:, path:, mtime:, }, - ... - ], - info: {oshash: object} - } + takes { + volume: '', + files: [ + {oshash:, path:, mtime:, }, + ... + ], + info: {oshash: object} + } - returns { - info: list, // list of files that need info - data: list, // list of flies that should be encoded to highest profile and uploaded - file: list // list of files that should be uploaded as is - } + returns { + info: list, // list of files that need info + data: list, // list of flies that should be encoded to highest profile and uploaded + file: list // list of files that should be uploaded as is + } ''' user = request.user upload_only = data.get('upload', False) @@ -110,16 +111,17 @@ actions.register(update, cache=False) @login_required_json def upload(request, data=None): ''' - takes { - id: string - frame: [] //multipart frames - file: [] //multipart file - } - - returns { - info: object, - rename: object - } + Uploads one or more media files for a given item + takes { + id: string // item id + frame: [] // one or more frames + file: [] // one or more files + } + returns { + info: object, // undocumented + rename: object // undocumented + } + see: add, edit, find, get, lookup, remove ''' response = json_response({}) f = get_object_or_404_json(models.File, oshash=request.POST['id']) @@ -157,15 +159,17 @@ actions.register(upload, cache=False) @login_required_json def addMedia(request, data): ''' - takes { - id: oshash - filename: string, - item: string - info: {} - } - returns { - item: id, - } + Adds media files to a given item + takes { + filename: string, // undocumented + id: oshash, // undocumented + info: {}, // undocumented + item: string // item id + } + returns { + item: id // item id + } + see: editMedia, moveMedia, removeMedia ''' response = json_response({}) oshash = data.pop('id') @@ -333,7 +337,7 @@ def taskStatus(request, data): status: string, // status, 'PENDING' or 'OK' result: object // result data } - notes: To be deprecated, will be wrapped in regular API call + notes: To be deprecated, will be wrapped in regular API call. ''' #FIXME: should check if user has permissions to get status if 'taskId' in data: @@ -348,14 +352,14 @@ actions.register(taskStatus, cache=False) @login_required_json def moveMedia(request, data): ''' - change file / item link - takes { - ids: ids of files - item: new public_id - } - - returns { - } + Move media files from one item to another + takes { + ids: ids of files + item: new public_id + } + returns {} + notes: This will *not* (yet) shift the corresponding annotations. + see: addMedia, editMedia, findMedia, removeMedia ''' if Item.objects.filter(public_id=data['item']).count() == 1: i = Item.objects.get(public_id=data['item']) @@ -395,17 +399,21 @@ actions.register(moveMedia, cache=False) @login_required_json def editMedia(request, data): ''' - change file / item link - takes { - files: [ - {id:, key1: value1, key2: value2} - ... - ] - } - possible keys: part, partTitle, language, ignore, extension, version, episodes - - returns { - } + Edits one or more media files + takes { + files: [ + { + id: string, // file id + key: value, // property id and new value + ... more key/value pairs + }, + // more media files + ] + } + returns {} + notes: Possible keys are 'episodes', 'extension', 'ignore', 'language', + 'part', 'partTitle' and 'version'. + see: addMedia, findMedia, moveMedia, removeMedia ''' ignore = [] save_items = [] @@ -452,6 +460,12 @@ actions.register(editMedia, cache=False) @login_required_json def removeMedia(request, data): + ''' + Removes one or more media files from a given item + takes {} // undocumented + returns {} // undocumented + see: addMedia, editMedia, findMedia, moveMedia + ''' response = json_response() if request.user.get_profile().get_level() == 'admin': qs = models.File.objects.filter(oshash__in=data['ids'], instances__id=None) @@ -471,14 +485,14 @@ actions.register(removeMedia, cache=False) def getPath(request, data): ''' - change file / item link - takes { - id: [hash of file] - } - - returns { - id: path - } + Undocumented + change file / item link + takes { + id: [hash of file] + } + returns { + id: path + } ''' response = json_response() ids = data['id'] @@ -527,77 +541,16 @@ def _order_query(qs, sort, prefix=''): def findMedia(request, data): ''' - takes { - 'query': query, - 'sort': array, - 'range': array - } - - query: item query object, more on query syntax at - https://wiki.0x2620.org/wiki/pandora/QuerySyntax - get media for all items matching the given query - - sort: array of key, operator dics - [ - { - key: "year", - operator: "-" - }, - { - key: "director", - operator: "" - } - ] - range: result range, array [from, to] - keys: array of keys to return - group: group elements by, country, genre, director... - - with keys, items is list of dicts with requested properties: - returns { - items: [object] - } - -Groups - takes { - 'query': query, - 'key': string, - 'group': string, - 'range': array - } - - query: query object, more on query syntax at - https://wiki.0x2620.org/wiki/pandora/QuerySyntax - range: result range, array [from, to] - keys: array of keys to return - group: group elements by, country, genre, director... - - possible values for keys: path, items - - with keys - items contains list of {'path': string, 'items': int}: - returns { - items: [object] - } - - without keys: return number of items in given query - returns { - items: int - } - -Positions - takes { - 'query': query, - 'positions': [string] - } - - query: query object, more on query syntax at - https://wiki.0x2620.org/wiki/pandora/QuerySyntax - positions: ids of items for which positions are required - returns { - positions: { - id: position - } - } + Finds media files + takes { + query: object, // query object, see `find` + sort: array, // list of sort objects, see `find` + range: [int, int] // range of results to return + } + returns { + items: [object] // list of items + } + see: addMedia, editMedia, moveMedia, removeMedia ''' if not data.get('sort'): data['sort'] = [{'key': 'path', 'operator': '+'}] @@ -664,12 +617,13 @@ actions.register(findMedia) def parsePath(request, data): #parse path and return info ''' - takes { - path: string - } - returns { - imdb: string - } + Parses a path + takes { + path: string // undocumented + } + returns { + imdb: string // undocumented + } ''' path = data['path'] response = json_response(ox.parse_movie_path(path)) @@ -678,13 +632,14 @@ actions.register(parsePath) def getMediaInfo(request, data): ''' - takes { - id: oshash of stream file - } - returns { - item: public_id, - file: oshash of source file - } + Gets media file info, undocumented + takes { + id: string // oshash of media file + } + returns { + item: string, // item id + file: string // oshash of source file + } ''' f = None qs = models.Stream.objects.filter(oshash=data['id']) diff --git a/pandora/event/views.py b/pandora/event/views.py index 36c4305a..ba006bce 100644 --- a/pandora/event/views.py +++ b/pandora/event/views.py @@ -19,14 +19,14 @@ import models @login_required_json def addEvent(request, data): ''' - Adds a calendar event + Adds a new calendar event takes { - name: string, - start: string, - end: string + end: string, // 'YYYY-MM-DD HH:MM:SS', arbitrary precision + name: string, // name + start: string // 'YYYY-MM-DD HH:MM:SS', arbitrary precision } returns { - id: string + id: string // event id } see: editEvent, findEvents, removeEvents ''' @@ -73,14 +73,15 @@ def editEvent(request, data): ''' Edits a calendar event takes { - id: string, - name: string, - start: string, - end: string + end: string, // 'YYYY-MM-DD HH:MM:SS', arbitrary precision + id: string, // event id + name: string, // event name + start: string // 'YYYY-MM-DD HH:MM:SS', arbitrary precision } returns { - id: string, - ... + id: string, // event id + key: value, // property id and value + ... // more key/value pairs } see: addEvent, findEvents, removeEvent ''' @@ -176,43 +177,14 @@ def findEvents(request, data): ''' Finds calendar events takes { - query: object, - sort: array - range': [int, int] + query: object, // query object, see `find` + sort: [object], // list of sort objects, see `find` + range: [int, int] // range of results to return } - - query: query object, more on query syntax at - https://wiki.0x2620.org/wiki/pandora/QuerySyntax - itemsQuery: { - //see find request - }, - sort: array of key, operator dics - [ - { - key: "year", - operator: "-" - }, - { - key: "director", - operator: "" - } - ] - range: result range, array [from, to] - - itemsQuery can be used to limit the resuts to matches in those items. - - with keys, items is list of dicts with requested properties: - returns {'status': {'code': int, 'text': string}, - 'data': {items: array}} - -Positions - takes { - query: object, - ids: [string] - } - query: query object, more on query syntax at - https://wiki.0x2620.org/wiki/pandora/QuerySyntax - ids: ids of events for which positions are required + returns { + items: [object] // list of items + } + see: addEvent, editEvent, removeEvent ''' response = json_response(status=200, text='ok') query = parse_query(data, request.user) diff --git a/pandora/item/views.py b/pandora/item/views.py index cefd2878..ed644373 100644 --- a/pandora/item/views.py +++ b/pandora/item/views.py @@ -499,6 +499,7 @@ def add(request, data): title: string, // title ... // more item properties } + notes: To allow for this, set config option `itemRequiresVideo` to false see: edit, find, get, lookup, remove, upload ''' if not request.user.get_profile().capability('canAddItems'): diff --git a/pandora/itemlist/views.py b/pandora/itemlist/views.py index 573cdec3..e0a3e38e 100644 --- a/pandora/itemlist/views.py +++ b/pandora/itemlist/views.py @@ -141,12 +141,12 @@ def addListItems(request, data): ''' Adds one or more items to a list takes { - list: listId, - items: [itemId], - query: ... - } - returns { + list: string, // list id + items: [string], // either list of item ids + query: object // or query object, see `find` } + returns {} + see: find, orderListItems, removeListItems ''' list = get_list_or_404_json(data['list']) if 'items' in data: @@ -171,12 +171,12 @@ def removeListItems(request, data): ''' Removes one or more items from a list takes { - list: listId, - items: [itemId], - quert: ... - } - returns { + list: string, // list id + items: [itemId], // either list of item ids + query: object // or query object, see `find` } + returns {} + see: addListItems, find, orderListItems ''' list = get_list_or_404_json(data['list']) if 'items' in data: @@ -197,14 +197,14 @@ actions.register(removeListItems, cache=False) @login_required_json def orderListItems(request, data): ''' - Sets the manual order of items in a given list + Sets the manual orderings of items in a given list takes { - list: string - ids: [string] - } - returns { + list: string, // list id + ids: [string] // ordered list of item ids } + returns {} notes: There is no UI for this yet. + see: addListItems, removeListItems ''' list = get_list_or_404_json(data['list']) response = json_response() @@ -225,22 +225,16 @@ def addList(request, data): ''' Adds a new list takes { - name: value, + name: value, // list name (optional) + ... // more key/value pairs } - possible keys to create list: - name - description - type - query - items - view - sort - returns { - id: string, - name: string, - ... + id: string, // list id + name: string, // list name + ... // more key/value pairs } + notes: Possible keys are 'description', 'items', 'name', 'query', 'sort', + 'type' and 'view'. see: editList, findLists, getList, removeList, sortLists ''' data['name'] = re.sub(' \[\d+\]$', '', data.get('name', 'Untitled')).strip() @@ -287,18 +281,18 @@ def editList(request, data): ''' Edits a list takes { - id: listId, - key: value, + id: string, // list id + key: value, // property id and new value + ... // more key/value pairs } - keys: name, status, query, position, posterFrames - if you change status you have to provide position of list - - posterFrames: - array with objects that have item/position returns { - id: string, - ... + id: string, // list id + ... // more key/value pairs } + notes: Possible keys are 'name', 'position', 'posterFrames', 'query' and + 'status'. 'posterFrames' is an array of {item, position}. If you change + 'status', you have to pass 'position' (the position of the list in its new + list folder). see: addList, findLists, getList, removeList, sortLists ''' list = get_list_or_404_json(data['id']) @@ -339,7 +333,8 @@ def subscribeToList(request, data): ''' Adds a list to favorites takes { - id: listId, + id: string, // list id + user: string // username (admin-only) } returns {} see: unsubscribeFromList @@ -365,8 +360,8 @@ def unsubscribeFromList(request, data): ''' Removes a list from favorites takes { - id: listId, - user: username(only admins) + id: string, // list id + user: string // username (admin-only) } returns {} see: subscribeToList @@ -386,12 +381,12 @@ def sortLists(request, data): ''' Set order of lists takes { - section: 'personal', - ids: [1,2,4,3] + section: string, // lists section + ids: [string] // ordered list of lists } - known sections: 'personal', 'public', 'featured' - featured can only be edited by admins returns {} + notes: Possible sections are 'personal', 'favorite' and 'featured'. Setting + the order of featured lists requires the appropriate capability. ''' position = 0 section = data['section'] diff --git a/pandora/news/views.py b/pandora/news/views.py index 401e28a6..8b95666c 100644 --- a/pandora/news/views.py +++ b/pandora/news/views.py @@ -15,21 +15,25 @@ import models def getNews(request, data): ''' - takes { - id: string - } - - returns { - id: string, - ... - } - - if not id is passed, return all news items - - takes {} - returns { - items: [object] - } + Gets one or all news items + takes { + id: string // news item id (optional) + } + returns { // if `id` is present + id: string, // news item id + key: value, // property id and value + ... // more key/value pairs + } or { // if `id` is missing + items: [ + { + id: string, // news item id + key: value, // property id and value + ... // more key/value pairs + }, + ... // more news items + ] + } + see: addNews, editNews, removeNews ''' response = json_response() if 'id' in data: @@ -44,15 +48,17 @@ actions.register(getNews) @login_required_json def addNews(request, data): ''' - takes { - title: string, - date: string, - text: text, - } - returns { - id: string, - ... - } + Adds a new news item + takes { + date: string, // date (format undocumented) + text: text, // text + title: string // title + } + returns { + id: string, // news item id + ... // more key/value pairs + } + see: editNews, getNews, removeNews ''' news = models.News() for key in ('title', 'text', 'date'): @@ -67,10 +73,12 @@ actions.register(addNews, cache=False) @login_required_json def removeNews(request, data): ''' - takes { - id: id - } - returns {} + Removes a news item + takes { + id: string // news item id + } + returns {} + see: addNews, editNews, getNews ''' response = json_response({}) news = get_object_or_404_json(models.News, id=ox.fromAZ(data['id'])) @@ -86,16 +94,18 @@ actions.register(removeNews, cache=False) @login_required_json def editNews(request, data): ''' - takes { - id: string, - title: string, - text: string, - date: string - } - returns { - id: string - ... - } + Edits a news item + takes { + date: string, // date (format undocumented) + id: string, // news item id + text: string, // text + title: string // title + } + returns { + id: string + ... + } + see: addNews, getNews, removeNews ''' response = json_response({}) n = get_object_or_404_json(models.News, id=ox.fromAZ(data['id'])) diff --git a/pandora/place/views.py b/pandora/place/views.py index 5697bd07..3bf4aa3f 100644 --- a/pandora/place/views.py +++ b/pandora/place/views.py @@ -20,7 +20,7 @@ import models @login_required_json def addPlace(request, data): ''' - Adds a place + Adds a new place takes { name: "", alternativeNames: [],