update api docs

pandora/edit/views.py

@@ -45,8 +45,9 @@ def addClips(request, data):
         ]
     }
     returns {}
-    notes: Clips are either {item, in, out} or {annotation}. If index is
+    notes: Clips are either {item, in, out} (by value) or {annotation} (by
-    missing, clips will be inserted at the end of the edit.
+    reference). If `index` is missing, clips will be inserted at the end of the
+    edit.
     see: editClip, orderClips, removeClips, sortClips
     '''
     response = json_response()

pandora/entity/views.py

@@ -31,14 +31,14 @@ def get_entity_or_404_json(id):
 @login_required_json
 def addEntity(request, data):
     '''
-        add entity
+    Adds an entity
     takes {
-            type:
+        type: string,
-            name:
+        name: string,
-            alternativeNames
+        alternativeNames: [string]
-        }
-        returns {
     }
+    returns {}
+    see: editEntity, findEntities, getEntity, removeEntity
     '''
     existing_names = []
     exists = False
@@ -97,6 +97,7 @@ def autocompleteEntities(request, data):
     returns {
         items: [{id, name,...}, ...] // array of matching entities
     }
+    see: autocomplete
     '''
     if not 'range' in data:
         data['range'] = [0, 10]
@@ -144,6 +145,7 @@ actions.register(autocompleteEntities)
 @login_required_json
 def editEntity(request, data):
     '''
+    Edits an entity
     takes {
         id: string
         name: string
@@ -154,6 +156,7 @@ def editEntity(request, data):
         id:
         ...
     }
+    see: addEntity, findEntities, getEntity, removeEntity
     '''
     response = json_response()
     entity = get_entity_or_404_json(data['id'])
@@ -197,20 +200,12 @@ def parse_query(data, user):
 
 def findEntities(request, data):
     '''
+    Finds entities for a given query
     takes {
-            query: {
+        query: object, // query object, see `find`
-                conditions: [
+        sort: [object], // list of sort objects, see `find`
-                    {
+        range: [int, int], // range of results
-                        key: 'name',
+        keys: [string] // list of properties to return
-                        value: 'something',
-                        operator: '='
-                    }
-                ]
-                operator: ","
-            },
-            sort: [{key: 'name', operator: '+'}],
-            range: [0, 100]
-            keys: []
     }
 
     possible query keys:
@@ -223,6 +218,7 @@ def findEntities(request, data):
     returns {
         items: [object]
     }
+    see: addEntity, editEntity, getEntity, removeEntity
     '''
     query = parse_query(data, request.user)
 
@@ -246,6 +242,7 @@ actions.register(findEntities)
 
 def getEntity(request, data):
     '''
+    Gets an entity by id
     takes {
         id: string,
         keys: [string]
@@ -253,6 +250,7 @@ def getEntity(request, data):
     returns {
         key: value
     }
+    see: addEntity, editEntity, findEntities, removeEntity
     '''
     response = json_response({})
     data['keys'] = data.get('keys', [])
@@ -264,6 +262,7 @@ actions.register(getEntity)
 @login_required_json
 def removeEntity(request, data):
     '''
+    Removes an entity
     takes {
         id: string,
         or
@@ -271,6 +270,7 @@ def removeEntity(request, data):
     }
     returns {
     }
+    see: addEntity, editEntity, findEntities, getEntity
     '''
     response = json_response()
 

pandora/event/views.py

@@ -19,6 +19,7 @@ import models
 @login_required_json
 def addEvent(request, data):
     '''
+    Adds a calendar event
     takes {
         name: string,
         start: string,
@@ -27,6 +28,7 @@ def addEvent(request, data):
     returns {
         id: string
     }
+    see: editEvent, findEvents, removeEvents
     '''
     existing_names = []
     exists = False
@@ -69,6 +71,7 @@ actions.register(addEvent, cache=False)
 @login_required_json
 def editEvent(request, data):
     '''
+    Edits a calendar event
     takes {
         id: string,
         name: string,
@@ -79,6 +82,7 @@ def editEvent(request, data):
         id: string,
         ...
     }
+    see: addEvent, findEvents, removeEvent
     '''
     event = get_object_or_404_json(models.Event, pk=ox.fromAZ(data['id']))
     if event.editable(request.user):
@@ -123,11 +127,12 @@ actions.register(editEvent, cache=False)
 @login_required_json
 def removeEvent(request, data):
     '''
-        remove Event with given id
+    Removes a calendar event
     takes {
         id: event id
     }
     returns {}
+    see: addEvent, editEvent, findEvents
     '''
     event = get_object_or_404_json(models.Event, pk=ox.fromAZ(data['id']))
     if event.editable(request.user):
@@ -169,6 +174,7 @@ def order_query(qs, sort):
 
 def findEvents(request, data):
     '''
+    Finds calendar events
     takes {
         query: object,
         sort: array
@@ -238,6 +244,7 @@ actions.register(findEvents)
 
 def getEventNames(request, data):
     '''
+    Undocumented
     takes {
     }
     returns {

pandora/item/views.py

@@ -160,6 +160,10 @@ def find(request, data):
     notes: Comparison operators are '=' (contains) '==' (is), '^' (starts with),
     '$' (ends with), '<', '<=', '>', or '>=', each optionally prefixed with '!'
     (not).
+    Leaving out `keys` or passing `positions` can be useful when building a
+    responsive GUI: First leave out `keys` to get totals as fast as possible,
+    then pass `positions` to get the positions of previously selected items,
+    finally make the query with `keys` and an appropriate range.
     see: add, edit, get, lookup, remove, upload
     '''
     if settings.JSON_DEBUG:

pandora/itemlist/views.py

@@ -59,19 +59,10 @@ def parse_query(data, user):
 def findLists(request, data):
     '''
     takes {
-            query: {
+        query: object, // query object, see `find`
-                conditions: [
+        sort: [], // list of sort objects, see `find`
-                    {
+        range: [int, int], // range of results
-                        key: 'user',
+        keys: [string] // properties to return
-                        value: 'something',
-                        operator: '='
-                    }
-                ]
-                operator: ","
-            },
-            sort: [{key: 'name', operator: '+'}],
-            range: [0, 100]
-            keys: []
     }
 
     possible query keys:
@@ -84,6 +75,7 @@ def findLists(request, data):
     returns {
         items: [{name: string, user: string, featured: bool, public...}]
     }
+    see: addList, editList, getList, removeList, sortLists
     '''
     query = parse_query(data, request.user)
 
@@ -121,6 +113,7 @@ actions.register(findLists)
 
 def getList(request, data):
     '''
+    Gets a list by id
     takes {
         id: listid
     }
@@ -129,6 +122,7 @@ def getList(request, data):
         section:
         ...
     }
+    see: addList, editList, findLists, removeList, sortLists
     '''
     if 'id' in data:
         response = json_response()
@@ -145,6 +139,7 @@ actions.register(getList)
 @login_required_json
 def addListItems(request, data):
     '''
+    Adds one or more items to a list
     takes {
         list: listId,
         items: [itemId],
@@ -174,6 +169,7 @@ actions.register(addListItems, cache=False)
 @login_required_json
 def removeListItems(request, data):
     '''
+    Removes one or more items from a list
     takes {
          list: listId,
          items: [itemId],
@@ -201,12 +197,14 @@ actions.register(removeListItems, cache=False)
 @login_required_json
 def orderListItems(request, data):
     '''
+    Sets the manual order of items in a given list
     takes {
        list: string
        ids: [string]
     }
     returns {
     }
+    notes: There is no UI for this yet.
     '''
     list = get_list_or_404_json(data['list'])
     response = json_response()
@@ -225,6 +223,7 @@ actions.register(orderListItems, cache=False)
 @login_required_json
 def addList(request, data):
     '''
+    Adds a new list
     takes {
         name: value,
     }
@@ -242,6 +241,7 @@ def addList(request, data):
         name: string,
         ...
     }
+    see: editList, findLists, getList, removeList, sortLists
     '''
     data['name'] = re.sub(' \[\d+\]$', '', data.get('name', 'Untitled')).strip()
     name = data['name']
@@ -285,6 +285,7 @@ actions.register(addList, cache=False)
 @login_required_json
 def editList(request, data):
     '''
+    Edits a list
     takes {
         id: listId,
         key: value,
@@ -298,6 +299,7 @@ def editList(request, data):
         id: string,
         ...
     }
+    see: addList, findLists, getList, removeList, sortLists
     '''
     list = get_list_or_404_json(data['id'])
     if list.editable(request.user):
@@ -313,11 +315,12 @@ actions.register(editList, cache=False)
 @login_required_json
 def removeList(request, data):
     '''
+    Removes a list
     takes {
-            id: listId,
+        id: string // list id
-        }
-        returns {
     }
+    returns {}
+    see: addList, editList, findLists, getList, sortLists
     '''
     list = get_list_or_404_json(data['id'])
     response = json_response()
@@ -334,11 +337,12 @@ actions.register(removeList, cache=False)
 @login_required_json
 def subscribeToList(request, data):
     '''
+    Adds a list to favorites
     takes {
         id: listId,
     }
-        returns {
+    returns {}
-        }
+    see: unsubscribeFromList
     '''
     list = get_list_or_404_json(data['id'])
     user = request.user
@@ -359,12 +363,13 @@ actions.register(subscribeToList, cache=False)
 @login_required_json
 def unsubscribeFromList(request, data):
     '''
+    Removes a list from favorites
     takes {
         id: listId,
         user: username(only admins)
     }
-        returns {
+    returns {}
-        }
+    see: subscribeToList
     '''
     list = get_list_or_404_json(data['id'])
     user = request.user
@@ -379,14 +384,14 @@ actions.register(unsubscribeFromList, cache=False)
 @login_required_json
 def sortLists(request, data):
     '''
+    Set order of lists
     takes {
         section: 'personal',
         ids: [1,2,4,3]
     }
     known sections: 'personal', 'public', 'featured'
     featured can only be edited by admins
-        returns {
+    returns {}
-        }
     '''
     position = 0
     section = data['section']

pandora/place/views.py

@@ -20,6 +20,7 @@ import models
 @login_required_json
 def addPlace(request, data):
     '''
+    Adds a place
     takes {
         name: "",
         alternativeNames: [],
@@ -102,6 +103,7 @@ actions.register(addPlace, cache=False)
 @login_required_json
 def editPlace(request, data):
     '''
+    Edits a place
     takes {
         id: string,
         name: string
@@ -167,10 +169,12 @@ actions.register(editPlace, cache=False)
 @login_required_json
 def removePlace(request, data):
     '''
+    Removes a place
     takes {
         id: string,
     }
     returns {}
+    see: addPlace, editPlace, findPlaces
     '''
     if isinstance(data, dict):
         data = data['id']
@@ -316,6 +320,7 @@ actions.register(findPlaces)
 
 def getPlaceNames(request, data):
     '''
+    Undocumented
     takes {}
     returns {
         items: [{name: string, matches: int}]