From 3950213960d43f2dc2bf5c70f062d615129ad3a6 Mon Sep 17 00:00:00 2001 From: rolux Date: Fri, 19 Dec 2014 15:31:57 +0000 Subject: [PATCH] update api docs --- pandora/archive/views.py | 11 +++++++--- pandora/document/views.py | 2 +- pandora/edit/views.py | 10 ++++----- pandora/entity/views.py | 17 +++++++-------- pandora/item/views.py | 2 +- pandora/itemlist/views.py | 11 +++++----- pandora/person/views.py | 2 +- pandora/sequence/views.py | 46 ++++++++++++++++++++------------------- pandora/text/views.py | 5 +++-- pandora/tv/views.py | 19 ++++++++-------- pandora/user/views.py | 3 ++- 11 files changed, 69 insertions(+), 59 deletions(-) diff --git a/pandora/archive/views.py b/pandora/archive/views.py index f0b5589c6..697dd2a84 100644 --- a/pandora/archive/views.py +++ b/pandora/archive/views.py @@ -29,6 +29,11 @@ from chunk import process_chunk @login_required_json def removeVolume(request, data): + ''' + Removes a volume + takes {} // undocumented + returns {} // undocumented + ''' user = request.user try: volume = models.Volume.objects.get(user=user, name=data['volume']) @@ -352,10 +357,10 @@ actions.register(taskStatus, cache=False) @login_required_json def moveMedia(request, data): ''' - Move media files from one item to another + Moves one or more media files from one item to another takes { - ids: ids of files - item: new public_id + ids: [string], // list of file ids + item: id // target item id } returns {} notes: This will *not* (yet) shift the corresponding annotations. diff --git a/pandora/document/views.py b/pandora/document/views.py index b629b57e3..0a912011b 100644 --- a/pandora/document/views.py +++ b/pandora/document/views.py @@ -250,7 +250,7 @@ def sortDocuments(request, data): Sets the sort order for the documents related to a given item takes { item: string, // item id - ids: [string] // list of document ids + ids: [string] // ordered list of document ids } returns {} see: addDocument, editDocument, findDocument, removeDocument, sortDocuments diff --git a/pandora/edit/views.py b/pandora/edit/views.py index 38a283414..1e2464a98 100644 --- a/pandora/edit/views.py +++ b/pandora/edit/views.py @@ -141,13 +141,12 @@ actions.register(editClip, cache=False) @login_required_json def orderClips(request, data): ''' - Updates manual ordering of clips within an edit + Sets the manual ordering of clips within a given edit takes { edit: string, // edit id ids: [string] // clip ids in new order } - returns { - } + returns {} see: addClips, editClip, removeClip, sortClips ''' edit = get_edit_or_404_json(data['edit']) @@ -207,7 +206,7 @@ def sortClips(request, data): sort: object // sort } returns {} - note: sort is [{key: string, operator: string}], operator can be '+' or '-' + notes: sort is [{key: string, operator: string}], operator can be '+' or '-' see: addClips, editClip, orderClips, removeClips ''' edit = get_edit_or_404_json(data['edit']) @@ -486,7 +485,8 @@ def sortEdits(request, data): ids: [string] // ordered list of edit ids } returns {} - notes: Sorting featured edits requires a specific per-user capability + notes: Setting the order of featured edits requires the appropriate + capability. see: addEdit, editEdits, findEdits, getEdit, removeEdit ''' position = 0 diff --git a/pandora/entity/views.py b/pandora/entity/views.py index 9d3266e0f..93ca52eea 100644 --- a/pandora/entity/views.py +++ b/pandora/entity/views.py @@ -240,11 +240,12 @@ def getEntity(request, data): ''' Gets an entity by id takes { - id: string, - keys: [string] + id: string, // entity id + keys: [string] // list of properties to return } returns { - key: value + key: value, // property id and value + ... // more key/value pairs } see: addEntity, editEntity, findEntities, removeEntity ''' @@ -258,14 +259,12 @@ actions.register(getEntity) @login_required_json def removeEntity(request, data): ''' - Removes an entity + Removes one or more entities takes { - id: string, - or - ids: [string] - } - returns { + id: string, // either entity id + ids: [string] // or list of entity ids } + returns {} see: addEntity, editEntity, findEntities, getEntity ''' response = json_response() diff --git a/pandora/item/views.py b/pandora/item/views.py index f5fe0f6a1..09c756ca0 100644 --- a/pandora/item/views.py +++ b/pandora/item/views.py @@ -582,7 +582,7 @@ def remove(request, data): id: string // item id } returns {} - notes: The return status is 200 for success or 403 for permission denied. + notes: The return status code is 200 for success or 403 for permission denied. see: add, edit, find, get, lookup, upload ''' response = json_response({}) diff --git a/pandora/itemlist/views.py b/pandora/itemlist/views.py index 753a3eb4f..011c145f9 100644 --- a/pandora/itemlist/views.py +++ b/pandora/itemlist/views.py @@ -110,12 +110,12 @@ def getList(request, data): ''' Gets a list by id takes { - id: listid + id: string // list id } returns { - id: - section: - ... + id: string, // list id + section: string, // lists section (like 'personal') + ... // more key/value pairs } see: addList, editList, findLists, removeList, sortLists ''' @@ -374,7 +374,7 @@ actions.register(unsubscribeFromList, cache=False) @login_required_json def sortLists(request, data): ''' - Set order of lists + Sets the order of lists in a given section takes { section: string, // lists section ids: [string] // ordered list of lists @@ -382,6 +382,7 @@ def sortLists(request, data): returns {} notes: Possible sections are 'personal', 'favorite' and 'featured'. Setting the order of featured lists requires the appropriate capability. + see: addList, editList, findLists, getList, removeList ''' position = 0 section = data['section'] diff --git a/pandora/person/views.py b/pandora/person/views.py index 290f9ff75..fb6081f97 100644 --- a/pandora/person/views.py +++ b/pandora/person/views.py @@ -54,7 +54,7 @@ def sortName(request, data): name: sortName, // sort name for this name ... // more results } - see editName, findNames + see: editName, findNames ''' names = data.get('names', []) if 'name' in data: diff --git a/pandora/sequence/views.py b/pandora/sequence/views.py index 51907fb4f..786091582 100644 --- a/pandora/sequence/views.py +++ b/pandora/sequence/views.py @@ -51,16 +51,17 @@ def order_query(qs, sort): def findSequences(request, data): ''' - takes { - query: ... - itemsQuery: ... - } - - one of your conditions has to be key: 'mode', value: [shape,color], operator: '==' - - returns { - items: [object] - } + Finds sequences for a given query + takes { + query: object // query object, see `find` + itemsQuery: object // limit to matching items, query object, see `find` + } + returns { + items: [object] // list of sequences + } + notes: One of the query conditions has to be {key: 'mode', operator: '==', + value: 'color' or 'shape'}. + see: find, getSequence ''' response = json_response() @@ -93,18 +94,19 @@ actions.register(findSequences) def getSequence(request, data): ''' - takes { - id - mode - position - } - - returns { - id - mode - in - out - } + Gets a sequence by id + takes { + id: string, // sequence id + mode: string, // sequence mode ('color' or 'shape') + position: int // position in seconds + } + returns { + id: string, // sequence id + mode: string, // sequence mode ('color' or 'shape') + in: int, // in point in seconds + out: int // out point in seconds + } + see: findSequences ''' response = json_response() position = float('%0.03f' % data['position']) diff --git a/pandora/text/views.py b/pandora/text/views.py index 3d7be7272..aabf00fab 100644 --- a/pandora/text/views.py +++ b/pandora/text/views.py @@ -202,7 +202,7 @@ def findTexts(request, data): } notes: Possible query keys are 'featured', 'name', 'subscribed' and 'user', possible keys are 'featured', 'name', 'query', 'subscribed' and 'user'. - see: addText, editText, getText, removeText, sortTexts + see: addText, editText, find, getText, removeText, sortTexts ''' query = parse_query(data, request.user) @@ -317,7 +317,8 @@ def sortTexts(request, data): ids: [string] // ordered list of text ids } returns {} - notes: Sorting featured texts requires the appropriate capability. + notes: Setting the order of featured texts requires the appropriate + capability. see: addText, findTexts, getText, editText, removeText ''' position = 0 diff --git a/pandora/tv/views.py b/pandora/tv/views.py index 0e745a9be..06d79820f 100644 --- a/pandora/tv/views.py +++ b/pandora/tv/views.py @@ -11,15 +11,16 @@ from ox.django.api import actions def tv(request, data): ''' - takes { - list: string - } - returns { - item: string, - position: float, - title: string, - ... - } + Gets TV program for a given list + takes { + list: string // list name + } + returns { + item: string, // current item + position: float, // current position in seconds + title: string, // item title + ... // more item properties + } ''' if 'list' in data and data['list']: list = get_list_or_404_json(data['list']) diff --git a/pandora/user/views.py b/pandora/user/views.py index 345f1224c..30a35508d 100644 --- a/pandora/user/views.py +++ b/pandora/user/views.py @@ -495,7 +495,7 @@ def findUsers(request, data): } notes: Possible query keys are 'browser', 'email', 'groups', 'lastLogin' and 'username'. - see: editUser, findUser, getUser, removeUser + see: editUser, find, findUser, getUser, removeUser ''' response = json_response(status=200, text='ok') query = parse_query(data, request.user) @@ -550,6 +550,7 @@ actions.register(getUser) @login_required_json def mail(request, data): ''' + Sends mail to a list of users takes { to: [string], // list of usernames of recipients subject: string, // subject