From 7cfdf7b8db11624ae9f21452daf388ede34d092c Mon Sep 17 00:00:00 2001
From: rolux <rolux@rolux.org>
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'])