From 7cfdf7b8db11624ae9f21452daf388ede34d092c Mon Sep 17 00:00:00 2001 From: rolux Date: Thu, 18 Dec 2014 18:18:18 +0000 Subject: [PATCH] update api docs --- pandora/document/views.py | 133 ++++++++++++++++++-------------------- pandora/edit/views.py | 126 +++++++++++++++++++----------------- pandora/item/views.py | 111 +++++++++++++++++-------------- 3 files changed, 192 insertions(+), 178 deletions(-) diff --git a/pandora/document/views.py b/pandora/document/views.py index 66b44bf69..52552c085 100644 --- a/pandora/document/views.py +++ b/pandora/document/views.py @@ -29,16 +29,13 @@ def get_document_or_404_json(id): @login_required_json def addDocument(request, data): ''' - add document(s) to item - takes { - item: string or [string] - - id: string - or - ids: [string] - } - returns { - } + Adds one or more documents to one or more items + takes { + item: string or [string], // one or more item ids + id: string or [string] // one or more document ids + } + returns {} + see: editDocument, findDocument, getDocument, removeDocument, sortDocuments ''' response = json_response() if 'ids' in data: @@ -68,16 +65,20 @@ actions.register(addDocument, cache=False) @login_required_json def editDocument(request, data): ''' - takes { - id: string - name: string - description: string - item(optional): edit descriptoin per item - } - returns { - id: - ... - } + takes { + id: string, // document id + name: string, // new document name + description: string // new document description + item: string // item id (optional) + } + returns { + id: + ... + } + notes: If `item` is present, this will not edit the global description of + the document, but its specific description in the context of the given + item. + see: addDocument, findDocument, getDocument, removeDocument, sortDocuments ''' response = json_response() item = 'item' in data and Item.objects.get(public_id=data['item']) or None @@ -140,32 +141,22 @@ def parse_query(data, user): def findDocuments(request, data): ''' - takes { - query: { - conditions: [ - { - key: 'user', - value: 'something', - operator: '=' - } - ] - operator: "," - }, - sort: [{key: 'name', operator: '+'}], - range: [0, 100] - keys: [] - } - - possible query keys: - name, user, extension, size - - possible keys: - name, user, extension, size - - } - returns { - items: [object] - } + takes { + query: object, // query object, see `find` + sort: [object], // list of sort objects, see `find` + range: [int, int], // range of results, per current sort order + keys: [string] // list of keys to return + } + returns { + items: [{ // list of documents + key: value, // item key and value + ... // more key/value pairs + }] + } + Notes: Query keys and keys to be returned can be 'extension', 'name', + 'size' and 'user'. + see: addDocument, editDocument, find, getDocument, removeDocument, + sortDocuments ''' query = parse_query(data, request.user) @@ -193,13 +184,16 @@ actions.register(findDocuments) def getDocument(request, data): ''' - takes { - id: string, - keys: [string] - } - returns { - key: value - } + Gets a document by id + takes { + id: string, // document id + keys: [string] // list of properties to return + } + returns { + key: value, // document key and value + ... // more key/value pairs + } + see: addDocument, editDocument, findDocument, removeDocument, sortDocuments ''' response = json_response({}) data['keys'] = data.get('keys', []) @@ -211,17 +205,15 @@ actions.register(getDocument) @login_required_json def removeDocument(request, data): ''' - takes { - id: string, - or - ids: [string] - item: string - } - - if item is passed, remove relation to item - otherwise remove document - returns { - } + Removes one or more documents, either from an item or from the database + takes { + id or ids: string or [string], // one or more document ids + item: string // item id (optional) + } + returns {} + notes: If `item` is present, this removes the documents from that item. + Otherwise, it removes the documents from the database. + see: addDocument, editDocument, findDocument, getDocument, sortDocuments ''' response = json_response() @@ -253,12 +245,13 @@ actions.register(removeDocument, cache=False) @login_required_json def sortDocuments(request, data): ''' - takes { - item: string - ids: [string] - } - returns { - } + Sets the sort order for the documents related to a given item + takes { + item: string, // item id + ids: [string] // list of document ids + } + returns {} + see: addDocument, editDocument, findDocument, removeDocument, sortDocuments ''' index = 0 item = Item.objects.get(public_id=data['item']) diff --git a/pandora/edit/views.py b/pandora/edit/views.py index 05224f6df..7fb46f9bb 100644 --- a/pandora/edit/views.py +++ b/pandora/edit/views.py @@ -244,14 +244,16 @@ actions.register(getEdit) @login_required_json def addEdit(request, data): ''' - takes { - [name], - [type] - } - returns { - id - ... - } + Adds an edit + takes { + name: string, // name (optional) + type: string // 'static' or 'smart' + } + returns { + id: string // edit id + ... // more edit properties + } + see: editEdit, findEdit, removeEdit, sortEdits ''' data['name'] = re.sub(' \[\d+\]$', '', data.get('name', 'Untitled')).strip() name = data['name'] @@ -299,12 +301,18 @@ actions.register(addEdit, cache=False) @login_required_json def editEdit(request, data): ''' - takes { - id - } - returns { - ... - } + Edits an edit (yes!) + takes { + id: string, // edit id + key: value, // property id and new value + ... // more key/value pairs + } + returns { + id: string, // edit id + key: value, // property id and new value + ... // more key/value pairs + } + see: addEdit, findEdit, removeEdit, sortEdits ''' edit = get_edit_or_404_json(data['id']) response = json_response() @@ -324,12 +332,12 @@ actions.register(editEdit, cache=False) @login_required_json def removeEdit(request, data): ''' - takes { - ... - } - returns { - ... - } + Removes an edit + takes { + id: string // edit id + } + returns {} + see: addEdit, editEdit findEdit, sortEdits ''' edit = get_edit_or_404_json(data['id']) response = json_response() @@ -373,32 +381,27 @@ def parse_query(data, user): def findEdits(request, data): ''' - takes { - query: { - conditions: [ - { - key: 'user', - value: 'something', - operator: '=' - } - ] - operator: "," - }, - sort: [{key: 'name', operator: '+'}], - range: [0, 100] - keys: [] - } + Finds edits for a given query + takes { + query: object, // query object, see `find` + sort: [], // list of sort objects, see `find` + range: [int, int], // range of results + keys: [string] // list of properties to return + } - possible query keys: - name, user, featured, subscribed + possible query keys: + name, user, featured, subscribed - possible keys: - name, user, featured, subscribed, query + possible keys: + name, user, featured, subscribed, query - } - returns { - items: [object] - } + } + returns { + items: [object] + } + notes: Possible query keys are 'featured', 'name', 'subscribed' and 'user', + possible keys are 'featured', 'name', 'query', 'subscribed' and 'user'. + see: editEdits, find, removeEdit, sortEdits ''' query = parse_query(data, request.user) @@ -437,10 +440,13 @@ actions.register(findEdits) @login_required_json def subscribeToEdit(request, data): ''' - takes { - id: string, - } - returns {} + Adds an edit to favorites + takes { + id: string, // edit id + user: string // username (admin-only) + } + returns {} + see: unsubscribeFromEdit ''' edit = get_edit_or_404_json(data['id']) user = request.user @@ -461,11 +467,12 @@ actions.register(subscribeToEdit, cache=False) @login_required_json def unsubscribeFromEdit(request, data): ''' - takes { - id: string, - user: username(only admins) - } - returns {} + takes { + id: string, // edit id + user: string // username (admin-only) + } + returns {} + see: subscribeToEdit ''' edit = get_edit_or_404_json(data['id']) user = request.user @@ -480,14 +487,13 @@ actions.register(unsubscribeFromEdit, cache=False) @login_required_json def sortEdits(request, data): ''' - takes { - section: 'personal', - ids: [1,2,4,3] - } - known sections: 'personal', 'public', 'featured' - featured can only be edited by admins - - returns {} + takes { + section: string, // 'personal', 'favorite' or 'featured' + ids: [string] // ordered list of edit ids + } + returns {} + notes: Sorting featured edits requires a specific per-user capability + see: editEdits, findEdits, removeEdit ''' position = 0 section = data['section'] diff --git a/pandora/item/views.py b/pandora/item/views.py index 166ed517d..2165c0b82 100644 --- a/pandora/item/views.py +++ b/pandora/item/views.py @@ -103,7 +103,7 @@ def find(request, data): Finds items for a given query takes { clipsQuery: object, // clips query object (optional) - group: string, // item key to group elements by + group: string, // item key to group results by (optional) keys: [string], // list of keys to return, [] for all (optional) positions: [string], // list of item ids (optional) query: { // query object @@ -125,34 +125,34 @@ def find(request, data): operator: string // sort order, '+' or '-' }] } - returns { // if `keys` is present (returns items) - items: [ + returns { // if `keys` is present + items: [ // returns list of matching items { id: string, // item id ... // more item properties }, ... // more items ] - } or { // if `clipsQuery` is present (returns clips) - clips: [ + } or { // if `clipsQuery` is present + clips: [ // returns list of matching clips { id: string, // clip id ... // more clip properties }, ... // more clips ] - } or { if `group` is present (returns results for filters) - items: [ + } or { // if `group` is present + items: [ // returns results for filters { name: string, // value for item key specified as group items: int // number of matches }, ... // more group objects ] - } or { // if `keys` is missing (returns totals) - items: int // total number of items - } or { // if `positions` is present (returns positions of given items) - positions: { + } or { // if `keys` is missing + items: int // returns total number of items + } or { // if `positions` is present () + positions: { // returns positions of given items id: position, // position of the item, per current sort order ... // more id/position pairs } @@ -160,7 +160,7 @@ def find(request, data): notes: Comparison operators are '=' (contains) '==' (is), '^' (starts with), '$' (ends with), '<', '<=', '>', or '>=', each optionally prefixed with '!' (not). - see: add, edit, remove + see: add, edit, get, lookup, remove, upload ''' if settings.JSON_DEBUG: print json.dumps(data, indent=2) @@ -288,13 +288,14 @@ def autocomplete(request, data): takes { key: string, value: string, - operator: string // '=', '==', '^', '$' - query: object // item query to limit results + operator: string, // '=', '==', '^', '$' + query: object, // item query to limit results, see `find` range: [int, int] } returns { items: [string, ...] // array of matching values } + see: autocompleteEntities ''' if not 'range' in data: data['range'] = [0, 10] @@ -348,6 +349,7 @@ actions.register(autocomplete) def findId(request, data): ''' + Undocumented takes { 'id': string 'title': string @@ -378,14 +380,16 @@ def getMetadata(request, data): ''' Gets metadata from an external service takes { - id: string, - keys: [string] + id: string, // item id + keys: [string] // list of item keys to return } - returns { - key: value - .. + key: value // item key and value + ... // more key/value pairs } + notes: This can be used to populate metadata from a remote source, like + IMDb. + see: getIds, updateExternalData ''' response = json_response({}) if settings.DATA_SERVICE: @@ -408,20 +412,23 @@ actions.register(getMetadata) def getIds(request, data): ''' - takes { - title: string, - director: [string], - year: int - } - - returns { - items: [{ - tite: string, - director: [string], - year: int, - originalTitle: string - }] - } + Gets ids from an external service + takes { + title: string, // title + director: [string], // list of directors + year: int // year + } + returns { + items: [{ + title: string, // title + director: [string], // list of directors + year: int, // year + originalTitle: string // original title + }] + } + notes: This can be used to populate metadata from a remote source, like + IMDb. + see: getMetadata, updateExternalData ''' response = json_response({}) if settings.DATA_SERVICE: @@ -435,13 +442,16 @@ actions.register(getIds) def get(request, data): ''' - takes { - id: string, - keys: [string] - } - returns { - key: value - } + Gets an item by id + takes { + id: string, // item id + keys: [string] // item properties to return + } + returns { + key: value, // item key and value + ... // more key/value pairs + } + see: add, edit, find, lookup, remove, upload ''' response = json_response({}) data['keys'] = data.get('keys', []) @@ -478,14 +488,14 @@ def add(request, data): ''' Adds a new item (without video) takes { - title: string, // item title (optional) + title: string, // title (optional) } returns { id: string, // item id - title: string, // item title + title: string, // title ... // more item properties } - see: edit, find, get, remove, upload + see: edit, find, get, lookup, remove, upload ''' if not request.user.get_profile().capability('canAddItems'): response = json_response(status=403, text='permissino denied') @@ -511,14 +521,14 @@ def edit(request, data): Edits metadata of an item takes { id: string, // item id - key: value, // property id and new value + key: value, // item key and new value ... // more key/value pairs } returns { - key: value // property id and new value + key: value // item key and new value ... // more key/value pairs } - see: add, find, get, remove, upload + see: add, find, get, lookup, remove, upload ''' update_clips = False item = get_object_or_404_json(models.Item, public_id=data['id']) @@ -561,13 +571,12 @@ actions.register(edit, cache=False) def remove(request, data): ''' Removes an item - remove item with id, return status is 200/removed on sucess or 403/permission deinied. takes { id: string // item id } returns {} notes: The return status is 200 for success or 403 for permission denied. - see: add, edit, find, get, upload + see: add, edit, find, get, lookup, upload ''' response = json_response({}) item = get_object_or_404_json(models.Item, public_id=data['id']) @@ -593,6 +602,7 @@ def setPosterFrame(request, data): position: float // position in seconds } returns {} + see: setPoster ''' item = get_object_or_404_json(models.Item, public_id=data['id']) if item.editable(request.user): @@ -621,6 +631,7 @@ def setPoster(request, data): width: int // width in px } } + see: setPosterFrame ''' item = get_object_or_404_json(models.Item, public_id=data['id']) response = json_response() @@ -649,6 +660,9 @@ def updateExternalData(request, data): id: string // item id } returns {} + notes: This can be used to populate metadata from a remote source, like + IMDb. + see: getIds, getMetadata ''' item = get_object_or_404_json(models.Item, public_id=data['id']) response = json_response() @@ -674,6 +688,7 @@ def lookup(request, data): title: string, // title year: string // year } + see: add, edit, find, get, remove, upload ''' if 'id' in data: i = models.Item.objects.get(public_id=data['id'])