api documentation takes and returns

pandora/annotation/views.py

@@ -64,7 +64,7 @@ def order_query(qs, sort):
 
 def findAnnotations(request):
     '''
-        param data {
+        takes {
             query: {
                 conditions: [],
                 operator: '&'
@@ -79,12 +79,9 @@ def findAnnotations(request):
             range: [in, out],
             sort: []
         }
-        return {
+        returns {
-            'status': {'code': int, 'text': string}
-            'data': {
             annotations = [{..}, {...}, ...]
         }
-        }
     '''
     data = json.loads(request.POST['data'])
     response = json_response()
@@ -117,19 +114,17 @@ actions.register(findAnnotations)
 @login_required_json
 def addAnnotation(request):
     '''
-        param data {
+        takes {
             item: itemId,
             layer: layerId,
             in: float,
             out: float,
             value: string
         }
-        return {'status': {'code': int, 'text': string},
+        returns {
-                'data': {
+            id: string, //id of new annotation
-                    id: 123, //id of new annotation
             ...
         }
-        }
     '''
     data = json.loads(request.POST['data'])
     for key in ('item', 'layer', 'in', 'out', 'value'):
@@ -160,7 +155,7 @@ actions.register(addAnnotation, cache=False)
 @login_required_json
 def addAnnotations(request):
     '''
-        param data {
+        takes {
             item: itemId,
             layer: layerId,
             annotations: [{
@@ -169,11 +164,8 @@ def addAnnotations(request):
                 value: string
             }, ...]
         }
-        return {'status': {'code': int, 'text': string},
+        returns {
-                'data': {
+            taskId: string
-                    id: 123, //id of new annotation
-                    ...
-                }
         }
     '''
     data = json.loads(request.POST['data'])
@@ -200,12 +192,10 @@ actions.register(addAnnotations, cache=False)
 @login_required_json
 def removeAnnotation(request):
     '''
-        param data {
+        takes {
             id: annotationId
         }
-        return {'status': {'code': int, 'text': string},
+        returns {
-                'data': {
-                }
         }
     '''
     response = json_response({})
@@ -223,18 +213,16 @@ actions.register(removeAnnotation, cache=False)
 @login_required_json
 def editAnnotation(request):
     '''
-        param data {
+        takes {
             id:,
             in: float,
             out: float,
             value: string,
         }
-        return {'status': {'code': int, 'text': string},
+        returns {
-                'data': {
             id:
             ...
         }
-        }
     '''
     response = json_response({})
     data = json.loads(request.POST['data'])

pandora/app/views.py

@@ -95,16 +95,13 @@ def robots_txt(request, url):
 
 def getPage(request):
     '''
-        param data {
+        takes {
             name: pagename
         }
-        return {
+        returns {
-            status: ...
-            data: {
             name:
             text:
         }
-        }
     '''
     data = json.loads(request.POST['data'])
     if isinstance(data, basestring):
@@ -123,17 +120,14 @@ actions.register(getPage)
 @login_required_json
 def editPage(request):
     '''
-        param data {
+        takes {
             name: pagename
             text: text
         }
-        return {
+        returns {
-            status: ...
-            data: {
             name:
             text:
         }
-        }
     '''
     if request.user.get_profile().capability('canEditSitePages'):
         data = json.loads(request.POST['data'])
@@ -151,8 +145,10 @@ actions.register(editPage)
 
 def init(request):
     '''
-        return {'status': {'code': int, 'text': string},
+        takes {}
-                'data': {user: object}}
+        returns {
+            user: object
+        }
     '''
     response = json_response({})
     config = copy.deepcopy(settings.CONFIG)
@@ -168,20 +164,15 @@ actions.register(init)
 def embedURL(request):
     '''
         
-        param data {
+        takes {
             url
             maxwidth
             maxheight
         }
-        return {
+        returns {
-            status: ...
-            data: {
             html
             ...
         }
-        }
-        return {'status': {'code': int, 'text': string},
-                'data': {user: object}}
     '''
     data = json.loads(request.POST['data'])
     response = json_response({})

pandora/archive/views.py

@@ -51,7 +51,7 @@ def update(request):
 
         call volume/files first and fill in requested info after that
 
-        param data {
+        takes {
             volume: '',
             files: [
                 {oshash:, path:, mtime:, },
@@ -60,14 +60,11 @@ def update(request):
             info: {oshash: object}
         }
 
-        return {
+        returns {
-            status: {'code': int, 'text': string},
-            data: {
             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
         }
-        }
     '''
     data = json.loads(request.POST['data'])
     user = request.user
@@ -76,8 +73,6 @@ def update(request):
     response = json_response({'info': [], 'data': [], 'file': []})
     volume = None
     if 'files' in data:
-        #update files info async, this takes to long otherwise
-        #FIXME: how can client know if update is done? possibly with taksStatus?
         t = tasks.update_files.delay(user.username, data['volume'], data['files'])
         response['data']['taskId'] = t.task_id
 
@@ -121,17 +116,16 @@ actions.register(update, cache=False)
 @login_required_json
 def upload(request):
     '''
+        takes {
             id: string
             frame: [] //multipart frames
             file: [] //multipart file
+        }
 
-        return {
+        returns {
-            status: {'code': int, 'text': string},
-            data: {
             info: object,
             rename: object
         }
-        }
     '''
     response = json_response({})
     f = get_object_or_404_json(models.File, oshash=request.POST['id'])
@@ -174,14 +168,13 @@ class VideoChunkForm(forms.Form):
 @login_required_json
 def addFile(request):
     '''
+        takes {
             id: oshash
             title: 
             info: {}
-        return {
-            status: {'code': int, 'text': string},
-            data: {
-                item: id,
         }
+        returns {
+            item: id,
         }
     '''
     response = json_response({})
@@ -298,15 +291,12 @@ actions.register(taskStatus, cache=False)
 def moveFiles(request):
     '''
         change file / item link
-        param data {
+        takes {
             ids: ids of files
             itemId: new itemId
         }
 
-        return {
+        returns {
-            status: {'code': int, 'text': string},
-            data: {
-            }
         }
     '''
     data = json.loads(request.POST['data'])
@@ -348,7 +338,7 @@ actions.register(moveFiles, cache=False)
 def editFiles(request):
     '''
         change file / item link
-        param data {
+        takes {
             files: [
                 {id:, key1: value1, key2: value2}
                 ...
@@ -356,10 +346,7 @@ def editFiles(request):
         }
         possible keys: part, partTitle, language, ignore, extension, version, episodes
 
-        return {
+        returns {
-            status: {'code': int, 'text': string},
-            data: {
-            }
         }
     '''
     data = json.loads(request.POST['data'])
@@ -419,16 +406,13 @@ actions.register(removeFiles, cache=False)
 def getPath(request):
     '''
         change file / item link
-        param data {
+        takes {
             id: [hash of file]
         }
 
-        return {
+        returns {
-            status: {'code': int, 'text': string},
-            data: {
             id: path
         }
-        }
     '''
     data = json.loads(request.POST['data'])
     response = json_response()
@@ -477,7 +461,7 @@ def _order_query(qs, sort, prefix=''):
 
 def findFiles(request):
     '''
-        param data {
+        takes {
             'query': query,
             'sort': array,
             'range': array
@@ -501,11 +485,12 @@ def findFiles(request):
             group:    group elements by, country, genre, director...
 
         with keys, items is list of dicts with requested properties:
-          return {'status': {'code': int, 'text': string},
+          returns {
-                'data': {items: array}}
+              items: [object]
+          }
 
 Groups
-        param data {
+        takes {
             'query': query,
             'key': string,
             'group': string,
@@ -522,30 +507,29 @@ Groups
 
         with keys
         items contains list of {'path': string, 'items': int}:
-        return {'status': {'code': int, 'text': string},
+        returns {
-            'data': {items: array}}
+            items: [object]
+        }
 
         without keys: return number of items in given query
-          return {'status': {'code': int, 'text': string},
+          returns {
-                'data': {items: int}}
+              items: int
+          }
 
 Positions
-        param data {
+        takes {
             'query': query,
-            'positions': []
+            '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
-        return {
+        returns {
-            status: {...},
-            data: {
             positions: {
                 id: position
             }
         }
-        }
     '''
     data = json.loads(request.POST['data'])
     if not data.get('sort'):
@@ -613,15 +597,12 @@ actions.register(findFiles)
 
 def parsePath(request): #parse path and return info
     '''
-        param data {
+        takes {
             path: string
         }
-        return {
+        returns {
-            status: {'code': int, 'text': string},
-            data: {
             imdb: string
         }
-        }
     '''
     path = json.loads(request.POST['data'])['path']
     response = json_response(ox.parse_movie_path(path))
@@ -630,16 +611,13 @@ actions.register(parsePath)
 
 def getFileInfo(request):
     '''
-        param data {
+        takes {
             id: oshash of stream file
         }
-        return {
+        returns {
-            status: {'code': int, 'text': string},
-            data: {
             item: itemId,
             file: oshash of source file
         }
-        }
     '''
     data = json.loads(request.POST['data'])
     f = None

pandora/clip/views.py

@@ -73,27 +73,24 @@ def order_query(qs, sort):
 
 def findClips(request):
     '''
-        param data {
+        takes {
             query: {
-                conditions: [],
+                conditions: [object],
-                operator: '&'
+                operator: string // '&' or '|'
             },
             itemsQuery: {
                 conditions: [],
-                operator: '&'
+                operator: string // '&' or '|'
             },
-            keys: [],
+            keys: [string],
             position: int,
-            positions: [],
+            positions: [string],
-            range: [in, out],
+            range: [int, int],
             sort: []
         }
 
-        return {
+        returns {
-            'status': {'code': int, 'text': string}
+            items: [object]
-            'data': {
-                items = [{..}, {...}, ...]
-            }
         }
     '''
     data = json.loads(request.POST['data'])

pandora/edit/views.py

@@ -13,14 +13,14 @@ import models
 @login_required_json
 def addClip(request):
     '''
-        param data
+        takes {
-            {timeline: timelineId,
+            item: string,
-             item: itemId,
+            edit: string,
             start: float,
             end: float,
         }
-        return {'status': {'code': int, 'text': string},
+        returns {
-                'data': {}}
+        }
     '''
     data = json.loads(request.POST['data'])
     list = get_object_or_404_json(models.Timeline, pk=data['list'])
@@ -43,12 +43,11 @@ actions.register(addClip, cache=False)
 @login_required_json
 def removeClip(request):
     '''
-        param data
+       takes {
-            {timeline: timelineId,
+           item: string
-             clip: clipId,
+        }
+        returns {
         }
-        return {'status': {'code': int, 'text': string},
-                'data': {}}
     '''
     data = json.loads(request.POST['data'])
     list = get_object_or_404_json(models.Timeline, pk=data['list'])
@@ -70,13 +69,12 @@ actions.register(removeClip, cache=False)
 
 def getTimeline(request):
     '''
-        param data
+        takes {
-            {name: value, user: user}
+            name: string,
-        return {
+            user: string
-            'status': {'code': int, 'text': string},
-            'data': {
-                fixme
         }
+        returns {
+            ...
         }
 
 could be
@@ -107,10 +105,12 @@ actions.register(getTimeline)
 @login_required_json
 def addTimeline(request):
     '''
-        param data
+        takes {
-            {name: value}
+            ...
-        return {'status': {'code': int, 'text': string},
+        }
-                'data': {}}
+        returns {
+            ...
+        }
     '''
     data = json.loads(request.POST['data'])
     if models.Timeline.filter(name=data['name'], user=request.user).count() == 0:
@@ -129,11 +129,11 @@ actions.register(addTimeline, cache=False)
 @login_required_json
 def editTimeline(request):
     '''
-        param data
+        takes {
-            {key: value}
+            ...
-        keys: name, public
+        }
-        return {'status': {'code': int, 'text': string},
+        returns {
-                'data': {}
+            ...
         }
     '''
     data = json.loads(request.POST['data'])
@@ -151,10 +151,12 @@ actions.register(editTimeline, cache=False)
 @login_required_json
 def removeTimeline(request):
     '''
-        param data
+        takes {
-            {key: value}
+            ...
-        return {'status': {'code': int, 'text': string},
+        }
-                'data': {}}
+        returns {
+            ...
+        }
     '''
     data = json.loads(request.POST['data'])
     list = get_object_or_404_json(models.Timeline, pk=data['list'])

pandora/event/views.py

@@ -18,13 +18,14 @@ import models
 @login_required_json
 def addEvent(request):
     '''
-        param data
+       takes {
-            {
+           name: string,
-                'name': '',
+           start: string,
-                'start': ''
+           end: string
-                'end': ''
+        }
+        returns {
+            id: string
         }
-            required keys: name, start, end
     '''
     data = json.loads(request.POST['data'])
     existing_names = []
@@ -67,13 +68,16 @@ actions.register(addEvent, cache=False)
 @login_required_json
 def editEvent(request):
     '''
-        param data
+        takes {
-            {
+            id: string,
-                'id': event id,
+            name: string,
-                'name': ''
+            start: string,
+            end: string
+        }
+        returns {
+            id: string,
             ...
         }
-            update provides keys of event with id
     '''
     data = json.loads(request.POST['data'])
     event = get_object_or_404_json(models.Event, pk=ox.fromAZ(data['id']))
@@ -118,11 +122,11 @@ actions.register(editEvent, cache=False)
 @login_required_json
 def removeEvent(request):
     '''
-        param data {
+        remove Event with given id
+        takes {
             id: event id
         }
-        remove Event with given id
+        returns {}
-
     '''
     data = json.loads(request.POST['data'])
     event = get_object_or_404_json(models.Event, pk=ox.fromAZ(data['id']))
@@ -164,8 +168,11 @@ def order_query(qs, sort):
 
 def findEvents(request):
     '''
-        param data
+        takes {
-            {'query': query, 'sort': array, 'range': array}
+            query: object,
+            sort: array
+            range': [int, int]
+        }
 
             query: query object, more on query syntax at
                    https://wiki.0x2620.org/wiki/pandora/QuerySyntax
@@ -188,13 +195,14 @@ def findEvents(request):
         itemsQuery can be used to limit the resuts to matches in those items.
         
         with keys, items is list of dicts with requested properties:
-          return {'status': {'code': int, 'text': string},
+          returns {'status': {'code': int, 'text': string},
                 'data': {items: array}}
 
 Positions
-        param data
+        takes {
-            {'query': query, 'ids': []}
+            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
@@ -231,18 +239,10 @@ actions.register(findEvents)
 
 def getEventNames(request):
     '''
-        param data {
+        takes {
-        }
-        return {
-                status: {
-                    code: int,
-                    text: string
-                },
-                data: {
-                    items: [
-                        {name:, matches}
-                    ]
         }
+        returns {
+            items: [{name: string, matches: int}]
         }
     '''
     response = json_response({})

pandora/item/views.py

@@ -104,7 +104,7 @@ def find(request):
                 sort: [{key: 'title', operator: '+'}]
             })
 
-        param data {
+        takes {
             'query': query,
             'sort': array,
             'range': array
@@ -129,11 +129,12 @@ def find(request):
             group:    group elements by, country, genre, director...
 
         with keys, items is list of dicts with requested properties:
-          return {'status': {'code': int, 'text': string},
+          returns {
-                'data': {items: array}}
+              items: [objects]
+          }
 
 Groups
-        param data {
+        takes {
             'query': query,
             'key': string,
             'group': string,
@@ -151,15 +152,17 @@ Groups
 
         with keys
         items contains list of {'name': string, 'items': int}:
-        return {'status': {'code': int, 'text': string},
+        returns {
-            'data': {items: array}}
+            items: [objects]
+        }
 
         without keys: return number of items in given query
-          return {'status': {'code': int, 'text': string},
+          returns {
-                'data': {items: int}}
+              items: int
+          }
 
 Positions
-        param data {
+        takes {
             'query': query,
             'positions': [],
             'sort': array
@@ -168,14 +171,11 @@ Positions
             query: query object, more on query syntax at
                    https://wiki.0x2620.org/wiki/pandora/QuerySyntax
             positions: ids of items for which positions are required
-        return {
+        returns {
-            status: {...},
-            data: {
             positions: {
                 id: position
             }
         }
-        }
     '''
     data = json.loads(request.POST['data'])
     if settings.JSON_DEBUG:
@@ -298,15 +298,16 @@ actions.register(find)
 
 def autocomplete(request):
     '''
-        param data
+        takes {
-            key
+            key: string,
-            value
+            value: string,
-            operator '=', '==', '^', '$'
+            operator: string // '=', '==', '^', '$'
-            query
+            query: object // item query to limit results
-            range
+            range: [int, int]
-        return 
+        }
-
+        returns {
-        query can be an item query to limit results
+            items: [string, ...] //array of matching values
+        }
     '''
     data = json.loads(request.POST['data'])
     if not 'range' in data:
@@ -359,11 +360,11 @@ actions.register(autocomplete)
 
 def findId(request):
     '''
-        param data {
+        takes {
-            'id':
+            'id': string
-            'title':
+            'title': string
-            'director': []
+            'director': [string]
-            'year': ...
+            'year': int
         }
     '''
     data = json.loads(request.POST['data'])
@@ -388,13 +389,13 @@ actions.register(findId)
 
 def getMetadata(request):
     '''
-        param data {
+        takes {
             id: string,
-            keys: array
+            keys: [string]
         }
 
         returns {
-           key: value,
+           key: value
            ..
         }
 
@@ -421,16 +422,20 @@ actions.register(getMetadata)
 
 def getIds(request):
     '''
-        param data {
+        takes {
-            title: '',
+            title: string,
-            director: [],
+            director: [string],
             year: int
         }
 
         returns {
-            items: [{tite, director, year, originalTitle}, ...]
+            items: [{
+                tite: string,
+                director: [string],
+                year: int,
+                originalTitle: string
+            }]
         }
-
     '''
     data = json.loads(request.POST['data'])
     response = json_response({})
@@ -445,11 +450,13 @@ actions.register(getIds)
 
 def get(request):
     '''
-        param data {
+        takes {
-            id: string
+            id: string,
-            keys: array
+            keys: [string]
+        }
+        returns {
+            key: value
         }
-        return item array
     '''
     response = json_response({})
     data = json.loads(request.POST['data'])
@@ -481,16 +488,14 @@ actions.register(get)
 @login_required_json
 def add(request):
     '''
-        param data {
+        takes {
+            title: string, //(optional)
         }
-        return {
+        returns {
-            status: {'code': int, 'text': string},
-            data: {
             id:
             name:
             ...
         }
-        }
     '''
 
     if not request.user.get_profile().capability('canAddItems'):
@@ -514,13 +519,17 @@ actions.register(add, cache=False)
 @login_required_json
 def edit(request):
     '''
-        param data {
+        edit item with id, you can pass one or many key/value pairs,
+        returns all key/values for edited item.
+
+        takes {
             id: string,
-            key: value,..
+            key: value,
+            ...
         }
-        return {
+        returns {
-            status: {'code': int, 'text': string},
+            key: value
-            data: {}
+            ..
         }
     '''
     update_clips = False
@@ -558,11 +567,13 @@ actions.register(edit, cache=False)
 @login_required_json
 def remove(request):
     '''
-        param data {
+        remove item with id, return status is 200/removed on sucess or 403/permission deinied.
+        takes {
             id: string
         }
 
-        return {'status': {'code': int, 'text': string}}
+        returns {
+        }
     '''
     response = json_response({})
     data = json.loads(request.POST['data'])
@@ -581,21 +592,13 @@ def remove(request):
     return render_to_json_response(response)
 actions.register(remove, cache=False)
 
-'''
+def setPosterFrame(request):
-    Poster API
-'''
-
-
-def setPosterFrame(request): #parse path and return info
     '''
-        param data {
+        takes {
-            id: itemId,
+            id: string,
             position: float
         }
-        return {
+        returns {
-            status: {'code': int, 'text': string},
-            data: {
-            }
         }
     '''
     data = json.loads(request.POST['data'])
@@ -610,16 +613,18 @@ def setPosterFrame(request): #parse path and return info
     return render_to_json_response(response)
 actions.register(setPosterFrame, cache=False)
 
-def setPoster(request): #parse path and return info
+
+def setPoster(request):
     '''
-        param data {
+        takes {
-            id: itemId,
+            id: string,
-            source: string
+            source: string // url
         }
-        return {
+        returns {
-            status: {'code': int, 'text': string},
+            poster: {
-            data: {
+                url: string,
-                poster: {url,width,height}
+                width: int,
+                height: int
             }
         }
     '''
@@ -645,14 +650,10 @@ actions.register(setPoster, cache=False)
 
 def updateExternalData(request):
     '''
-        param data {
+        takes {
-            id: itemId,
+            id: string,
-        }
-        return {
-            status: {'code': int, 'text': string},
-            data: {
-                poster: {url,width,height}
         }
+        returns {
         }
     '''
     data = json.loads(request.POST['data'])
@@ -667,21 +668,18 @@ actions.register(updateExternalData, cache=False)
 
 def lookup(request):
     '''
-        param data {
+        takes {
             title: string,
             director: [string],
             year: string,
             id: string
         }
-        return {
+        returns {
-            status: {'code': int, 'text': string},
-            data: {
             title: string,
             director: [string],
             year: string,
             id: string
         }
-        }
     '''
     data = json.loads(request.POST['data'])
     if 'id' in data:
@@ -695,33 +693,7 @@ def lookup(request):
     return render_to_json_response(response)
 actions.register(lookup)
 
-def getImdbId(request):
-    '''
-        param data {
-            title: string,
-            director: string,
-            year: string
-        }
-        return {
-            status: {'code': int, 'text': string},
-            data: {
-                imdbId:string
-            }
-        }
-    '''
-    data = json.loads(request.POST['data'])
-    imdbId = ox.web.imdb.getImdbId(data['title'], data['director'], timeout=-1)
-    if imdbId:
-        response = json_response({'imdbId': imdbId})
-    else:
-        response = json_response(status=404, text='not found')
-    return render_to_json_response(response)
-actions.register(getImdbId)
 
-
-'''
-    media delivery
-'''
 def frame(request, id, size, position=None):
     item = get_object_or_404(models.Item, itemId=id)
     if not item.access(request.user):

pandora/itemlist/views.py

@@ -57,7 +57,7 @@ def parse_query(data, user):
 
 def findLists(request):
     '''
-        param data {
+        takes {
             query: {
                 conditions: [
                     {
@@ -80,12 +80,8 @@ def findLists(request):
             name, user, featured, subscribed, query
 
         }
-        return {status: {code: int, text: string},
+        returns {
-                data: {
+            items: [{name: string, user: string, featured: bool, public...}]
-                    items: [
-                        {name:, user:, featured:, public...}
-                    ]
-                }
         }
     '''
     data = json.loads(request.POST['data'])
@@ -126,15 +122,12 @@ actions.register(findLists)
 @login_required_json
 def addListItems(request):
     '''
-        param data {
+        takes {
             list: listId,
             items: [itemId],
             query: ...
         }
-        return {
+        returns {
-            status: {'code': int, 'text': string},
-            data: {
-            }
         }
     '''
     data = json.loads(request.POST['data'])
@@ -158,15 +151,12 @@ actions.register(addListItems, cache=False)
 @login_required_json
 def removeListItems(request):
     '''
-        param data {
+        takes {
              list: listId,
              items: [itemId],
              quert: ...
         }
-        return {
+        returns {
-            status: {'code': int, 'text': string},
-            data: {
-            }
         }
     '''
     data = json.loads(request.POST['data'])
@@ -189,7 +179,7 @@ actions.register(removeListItems, cache=False)
 @login_required_json
 def addList(request):
     '''
-        param data {
+        takes {
             name: value,
         }
         possible keys to create list:
@@ -201,14 +191,11 @@ def addList(request):
             view
             sort
 
-        return {
+        returns {
-            status: {'code': int, 'text': string},
+            id: string,
-            data: {
+            name: string,
-                id:
-                name:
             ...
         }
-        }
     '''
     data = json.loads(request.POST['data'])
     data['name'] = re.sub(' \[\d+\]$', '', data.get('name', 'Untitled')).strip()
@@ -252,7 +239,7 @@ actions.register(addList, cache=False)
 @login_required_json
 def editList(request):
     '''
-        param data {
+        takes {
             id: listId,
             key: value,
         }
@@ -261,10 +248,9 @@ def editList(request):
 
         posterFrames:
             array with objects that have item/position
-        return {
+        returns {
-            status: {'code': int, 'text': string},
+            id: string,
-            data: {
+            ...
-            }
         }
     '''
     data = json.loads(request.POST['data'])
@@ -281,13 +267,10 @@ actions.register(editList, cache=False)
 @login_required_json
 def removeList(request):
     '''
-        param data {
+        takes {
             id: listId,
         }
-        return {
+        returns {
-            status: {'code': int, 'text': string},
-            data: {
-            }
         }
     '''
     data = json.loads(request.POST['data'])
@@ -305,13 +288,10 @@ actions.register(removeList, cache=False)
 @login_required_json
 def subscribeToList(request):
     '''
-        param data {
+        takes {
             id: listId,
         }
-        return {
+        returns {
-            status: {'code': int, 'text': string},
-            data: {
-            }
         }
     '''
     data = json.loads(request.POST['data'])
@@ -333,14 +313,11 @@ actions.register(subscribeToList, cache=False)
 @login_required_json
 def unsubscribeFromList(request):
     '''
-        param data {
+        takes {
             id: listId,
             user: username(only admins)
         }
-        return {
+        returns {
-            status: {'code': int, 'text': string},
-            data: {
-            }
         }
     '''
     data = json.loads(request.POST['data'])
@@ -356,16 +333,13 @@ actions.register(unsubscribeFromList, cache=False)
 @login_required_json
 def sortLists(request):
     '''
-        param data {
+        takes {
             section: 'personal',
             ids: [1,2,4,3]
         }
         known sections: 'personal', 'public', 'featured'
         featured can only be edited by admins
-        return {
+        returns {
-            status: {'code': int, 'text': string},
-            data: {
-            }
         }
     '''
     data = json.loads(request.POST['data'])

pandora/log/views.py

@@ -17,17 +17,12 @@ import models
 
 def log(request):
     '''
-        param data {
+        takes {
-            url: url
+            url: string,
-            line: line
+            line: string,
-            text: text
+            text: string
-        }
-        return {
-            status: ...
-            data: {
-                name:
-                body:
         }
+        returns {
         }
     '''
     data = json.loads(request.POST['data'])
@@ -53,10 +48,10 @@ actions.register(log, cache=False)
 @admin_required_json
 def removeLogs(request):
     '''
-        param data {
+        takes {
-            'ids': ,
+            ids: [string]
         }
-        can contain any of the allowed keys for place 
+        returns {}
     '''
     data = json.loads(request.POST['data'])
     models.Log.objects.filter(id__in=[ox.fromAZ(i) for i in data['ids']]).delete()
@@ -91,7 +86,7 @@ def order_query(qs, sort):
 @admin_required_json
 def findLogs(request):
     '''
-        param data {
+        takes {
             query: {
                 conditions: [
                     {
@@ -103,8 +98,11 @@ def findLogs(request):
                 operator: ","
             },
             sort: [{key: 'created', operator: '+'}],
-            range: [0, 100]
+            range: [int, int]
-            keys: []
+            keys: [string]
+        }
+        returns {
+            items: [object]
         }
 
     '''

pandora/news/views.py

@@ -14,14 +14,20 @@ import models
 
 def getNews(request):
     '''
-        param data {
+        takes {
+            id: string
         }
 
-        return {
+        returns {
-            'status': {'code': int, 'text': string}
+            id: string,
-            'data': {
+            ...
-                items = [{..}, {...}, ...]
         }
+
+        if not id is passed, return all news items
+
+        takes {}
+        returns {
+            items: [object]
         }
     '''
     data = json.loads(request.POST['data'])
@@ -38,17 +44,15 @@ actions.register(getNews)
 @login_required_json
 def addNews(request):
     '''
-        param data {
+        takes {
             title: string,
             date: string,
             text: text,
         }
-        return {'status': {'code': int, 'text': string},
+        returns {
-                'data': {
+            id: string,
-                    id: 123,
             ...
         }
-        }
     '''
     data = json.loads(request.POST['data'])
 
@@ -64,13 +68,10 @@ actions.register(addNews, cache=False)
 @login_required_json
 def removeNews(request):
     '''
-        param data {
+        takes {
             ids: []
         }
-        return {'status': {'code': int, 'text': string},
+        returns {}
-                'data': {
-                }
-        }
     '''
     data = json.loads(request.POST['data'])
     response = json_response({})
@@ -86,18 +87,16 @@ actions.register(removeNews, cache=False)
 @login_required_json
 def editNews(request):
     '''
-        param data {
+        takes {
-            id:,
+            id: string,
-            title:
+            title: string,
-            text:
+            text: string,
-            date:
+            date: string
         }
-        return {'status': {'code': int, 'text': string},
+        returns {
-                'data': {
+            id: string
-                    id:
             ...
         }
-        }
     '''
     response = json_response({})
     data = json.loads(request.POST['data'])

pandora/person/views.py

@@ -17,11 +17,15 @@ import tasks
 @admin_required_json
 def editName(request):
     '''
-        param data {
+        takes {
-            'id': nameid,
+            id: id,
-            'sortname': ...
+            sortname: string
+        }
+        returns {
+            id: string,
+            name: string
+            ...
         }
-        can contain any of the allowed keys for name 
     '''
     data = json.loads(request.POST['data'])
     person = get_object_or_404_json(models.Person, pk=ox.fromAZ(data['id']))
@@ -37,12 +41,14 @@ actions.register(editName, cache=False)
 
 def sortName(request):
     '''
-        param data {
+        get sort name(s) for given name or names
-            'name': name
+        takes {
-            or
+            names: [string]
-            'names': [name, name]
+            name: string
+        }
+        returns {
+            name: sortName
         }
-        can contain any of the allowed keys for name 
     '''
     data = json.loads(request.POST['data'])
     names = data.get('names', [])
@@ -85,7 +91,7 @@ def order_query(qs, sort):
 
 def findNames(request):
     '''
-        param data {
+        takes {
             query: {
                 conditions: [
                     {
@@ -110,16 +116,8 @@ def findNames(request):
         possible keys:
             name, sortname, numberofnames
         
-        return {
+        returns {
-                status: {
+            items: [{name:, user:, featured:, public...}]
-                    code: int,
-                    text: string
-                },
-                data: {
-                    items: [
-                        {name:, user:, featured:, public...}
-                    ]
-                }
         }
         param data
             {'query': query, 'sort': array, 'range': array}
@@ -140,9 +138,9 @@ def findNames(request):
             range:       result range, array [from, to]
 
         with keys, items is list of dicts with requested properties:
-          return {'status': {'code': int, 'text': string},
+        returns {
-                'data': {items: array}}
+              items: [string]
-
+        }
     '''
     data = json.loads(request.POST['data'])
     response = json_response()

pandora/place/views.py

@@ -19,7 +19,7 @@ import models
 @login_required_json
 def addPlace(request):
     '''
-        param data {
+        takes {
             name: "",
             alternativeNames: [],
             geoname: "",
@@ -33,6 +33,9 @@ def addPlace(request):
             area: float,
             type: ""
         }
+        returns {
+            id: string
+        }
     '''
     #FIXME: check permissions
     data = json.loads(request.POST['data'])
@@ -95,12 +98,14 @@ actions.register(addPlace, cache=False)
 @login_required_json
 def editPlace(request):
     '''
-        param data {
+        takes {
-            'id': placeid,
+            id: string,
-            'name': ...
+            name: string
-            'north': 0...
+            north: int
+        }
+        returns {
+            names: []
         }
-        can contain any of the allowed keys for place 
     '''
     data = json.loads(request.POST['data'])
     place = get_object_or_404_json(models.Place, pk=ox.fromAZ(data['id']))
@@ -158,9 +163,10 @@ actions.register(editPlace, cache=False)
 @login_required_json
 def removePlace(request):
     '''
-        param data {
+        takes {
-            'id': placeid,
+            id: string,
         }
+        returns {}
     '''
     data = json.loads(request.POST['data'])
     if isinstance(data, dict):
@@ -205,7 +211,7 @@ def order_query(qs, sort):
 
 def findPlaces(request):
     '''
-        param data {
+        takes {
             query: {
                 conditions: [
                     {
@@ -220,8 +226,8 @@ def findPlaces(request):
                 //see find request
             },
             sort: [{key: 'name', operator: '+'}],
-            range: [0, 100]
+            range: [int, int]
-            keys: []
+            keys: [string]
         }
 
         possible query keys:
@@ -233,20 +239,14 @@ def findPlaces(request):
         possible keys:
             name, geoname, user
         
-        return {
+        returns {
-                status: {
+            items: [object]
-                    code: int,
-                    text: string
-                },
-                data: {
-                    items: [
-                        {name:, user:, featured:, public...}
-                    ]
         }
+        takes {
+            query: object,
+            sort: [object]
+            range: [int, int]
         }
-        param data
-            {'query': query, 'sort': array, 'range': array}
-
             query: query object, more on query syntax at
                    https://wiki.0x2620.org/wiki/pandora/QuerySyntax
             sort: array of key, operator dics
@@ -263,13 +263,15 @@ def findPlaces(request):
             range:       result range, array [from, to]
 
         with keys, items is list of dicts with requested properties:
-          return {'status': {'code': int, 'text': string},
+        returns {
-                'data': {items: array}}
+            items: [string]    
+        }
 
 Positions
-        param data
+        takes {
-            {'query': query, 'positions': []}
+            query: object,
-
+            positions: [string]
+        }
         query: query object, more on query syntax at
                https://wiki.0x2620.org/wiki/pandora/QuerySyntax
         positions:  ids of places for which positions are required
@@ -311,18 +313,9 @@ actions.register(findPlaces)
 
 def getPlaceNames(request):
     '''
-        param data {
+        takes {}
-        }
+        returns {
-        return {
+            items: [{name: string, matches: int}]
-                status: {
-                    code: int,
-                    text: string
-                },
-                data: {
-                    items: [
-                        {name:, matches}
-                    ]
-                }
         }
     '''
     response = json_response({})

pandora/sequence/views.py

@@ -50,18 +50,15 @@ def order_query(qs, sort):
 
 def findSequences(request):
     '''
-        param data {
+        takes {
             query: ...
             itemsQuery: ...
         }
 
         one of your conditions has to be key: 'mode', value: [shape,color], operator: '=='
 
-        return {
+        returns {
-            'status': {'code': int, 'text': string}
+            items: [object]
-            'data': {
-                items = [{..}, {...}, ...]
-            }
         }
     '''
     data = json.loads(request.POST['data'])
@@ -96,21 +93,18 @@ actions.register(findSequences)
 
 def getSequence(request):
     '''
-        param data {
+        takes {
             id
             mode 
             position
         }
 
-        return {
+        returns {
-            'status': {'code': int, 'text': string}
-            'data': {
             id
             mode
             in
             out
         }
-        }
     '''
     data = json.loads(request.POST['data'])
     response = json_response()

pandora/text/views.py

@@ -27,17 +27,14 @@ def get_text_or_404_json(id):
 @login_required_json
 def addText(request):
     '''
-        param data {
+        takes {
             name: value,
         }
-        return {
+        returns {
-            status: {'code': int, 'text': string},
-            data: {
             id:
             name:
             ...
         }
-        }
     '''
     data = json.loads(request.POST['data'])
     data['name'] = re.sub(' \[\d+\]$', '', data.get('name', 'Untitled')).strip()
@@ -74,10 +71,10 @@ actions.register(addText, cache=False)
 
 def getText(request):
     '''
-        param data {
+        takes {
             id: textid
         }
-        return {
+        returns {
             id:
             text:
             ...
@@ -106,12 +103,12 @@ actions.register(getText)
 @login_required_json
 def editText(request):
     '''
-        param data {
+        takes {
             id:
             text:
             public: boolean
         }
-        return {
+        returns {
             id:
             text:
             ...
@@ -178,7 +175,7 @@ def parse_query(data, user):
 
 def findTexts(request):
     '''
-        param data {
+        takes {
             query: {
                 conditions: [
                     {
@@ -201,12 +198,8 @@ def findTexts(request):
             name, user, featured, subscribed, query
 
         }
-        return {status: {code: int, text: string},
+        returns {
-                data: {
+            items: [object]
-                    items: [
-                        {name:, user:, featured:, public...}
-                    ]
-                }
         }
     '''
     data = json.loads(request.POST['data'])
@@ -248,13 +241,10 @@ actions.register(findTexts)
 @login_required_json
 def removeText(request):
     '''
-        param data {
+        takes {
-            id: testId,
+            id: string,
-        }
-        return {
-            status: {'code': int, 'text': string},
-            data: {
         }
+        returns {
         }
     '''
     data = json.loads(request.POST['data'])
@@ -271,14 +261,10 @@ actions.register(removeText, cache=False)
 @login_required_json
 def subscribeToText(request):
     '''
-        param data {
+        takes {
-            id: testId,
+            id: string,
-        }
-        return {
-            status: {'code': int, 'text': string},
-            data: {
-            }
         }
+        returns {}
     '''
     data = json.loads(request.POST['data'])
     text = get_text_or_404_json(data['id'])
@@ -299,15 +285,11 @@ actions.register(subscribeToText, cache=False)
 @login_required_json
 def unsubscribeFromText(request):
     '''
-        param data {
+        takes {
-            id: testId,
+            id: string,
             user: username(only admins)
         }
-        return {
+        returns {}
-            status: {'code': int, 'text': string},
-            data: {
-            }
-        }
     '''
     data = json.loads(request.POST['data'])
     text = get_text_or_404_json(data['id'])
@@ -322,17 +304,14 @@ actions.register(unsubscribeFromText, cache=False)
 @login_required_json
 def sortTexts(request):
     '''
-        param data {
+        takes {
             section: 'personal',
             ids: [1,2,4,3]
         }
             known sections: 'personal', 'public', 'featured'
             featured can only be edited by admins
-        return {
+
-            status: {'code': int, 'text': string},
+        returns {}
-            data: {
-            }
-        }
     '''
     data = json.loads(request.POST['data'])
     position = 0

pandora/title/views.py

@@ -17,11 +17,14 @@ import models
 @admin_required_json
 def editTitle(request):
     '''
-        param data {
+        takes {
-            'id': titleid,
+            id: string
-            'sorttitle': ...
+            sorttitle: string
         }
         can contain any of the allowed keys for title 
+        returns {
+            id: string
+        }
     '''
     data = json.loads(request.POST['data'])
     title = get_object_or_404_json(models.Title, pk=ox.fromAZ(data['id']))
@@ -65,7 +68,7 @@ def order_query(qs, sort):
 
 def findTitles(request):
     '''
-        param data {
+        takes {
             query: {
                 conditions: [
                     {
@@ -90,19 +93,15 @@ def findTitles(request):
         possible keys:
             title, sorttitle, numberoftitles
         
-        return {
+        returns {
-                status: {
+            items: [object]
-                    code: int,
-                    text: string
-                },
-                data: {
-                    items: [
-                        {title:, user:, featured:, public...}
-                    ]
         }
+
+        takes {
+            query: object,
+            sort: [object],
+            range: [int, int]
         }
-        param data
-            {'query': query, 'sort': array, 'range': array}
 
             query: query object, more on query syntax at
                    https://wiki.0x2620.org/wiki/pandora/QuerySyntax
@@ -120,8 +119,7 @@ def findTitles(request):
             range:       result range, array [from, to]
 
         with keys, items is list of dicts with requested properties:
-          return {'status': {'code': int, 'text': string},
+          returns {items: [object]}
-                'data': {items: array}}
 
     '''
     data = json.loads(request.POST['data'])

pandora/tv/views.py

@@ -10,6 +10,17 @@ from itemlist.views import get_list_or_404_json
 from ox.django.api import actions
 
 def tv(request):
+    '''
+        takes {
+            list: string
+        }
+        returns {
+            item: string,
+            position: float,
+            title: string,
+            ...
+        }
+    '''
     data = json.loads(request.POST['data'])
     if 'list' in data and data['list']:
         list = get_list_or_404_json(data['list'])

pandora/user/views.py

@@ -25,14 +25,12 @@ import models
 
 def signin(request):
     '''
-        param data {
+        takes {
-            username: 'username',
+            username: string,
-            password: 'password'
+            password: string
         }
 
-        return {
+        returns {
-            status: {'code': 200, 'text': 'ok'}
-            data: {
             errors: {
                 username: 'Unknown Username',
                 password: 'Incorrect Password'
@@ -41,7 +39,6 @@ def signin(request):
                 ...
             }
         }
-        }
     '''
     data = json.loads(request.POST['data'])
     if 'username' in data and 'password' in data:
@@ -84,17 +81,13 @@ actions.register(signin, cache=False)
 
 def signout(request):
     '''
-        param data {
+        takes {}
-        }
 
-        return {
+        returns {
-            status: {'code': int, 'text': string}
-            data: {
             user: {
                 default user
             }
         }
-        }
     '''
     response = json_response(text='ok')
     if request.user.is_authenticated():
@@ -112,15 +105,13 @@ actions.register(signout, cache=False)
 
 def signup(request):
     '''
-        param data {
+        takes {
-            username: 'username',
+            username: string,
-            password: 'password',
+            password: string,
-            email: 'emailaddress'
+            email: string
         }
 
-        return {
+        returns {
-            status: {'code': int, 'text': string}
-            data: {
             errors: {
                 username: 'Unknown Username',
                 password: 'Incorrect Password'
@@ -129,7 +120,6 @@ def signup(request):
                 ...
             }
         }
-        }
     '''
     data = json.loads(request.POST['data'])
     if 'username' in data and 'password' in data:
@@ -196,22 +186,19 @@ actions.register(signup, cache=False)
 
 def resetPassword(request):
     '''
-        param data {
+        takes {
-            username: username,
+            username: string,
-            password: new password
+            password: string,
-            code: reset code 
+            code: string
         }
 
-        return {
+        returns {
-            status: {'code': int, 'text': string}
-            data: {
             errors: {
                 code: 'Incorrect Code'
             }
             user {
             }
         }
-        }
     '''
     data = json.loads(request.POST['data'])
     if 'code' in data and 'password' in data:
@@ -252,21 +239,18 @@ actions.register(resetPassword, cache=False)
 
 def requestToken(request):
     '''
-        param data {
+        takes {
-            username: username,
+            username: string,
-            email: email
+            email: string
         }
 
-        return {
+        returns {
-            status: {'code': int, 'text': string}
-            data: {
             errors: {
                 username: 'Unknown Username'
                 email: 'Unknown Email'
             }
             username: user
         }
-        }
     '''
     data = json.loads(request.POST['data'])
     user = None
@@ -321,16 +305,13 @@ actions.register(requestToken, cache=False)
 @admin_required_json
 def editUser(request):
     '''
-        param data {
+        takes {
             key: value
         }
         required key: id 
         optional keys: username, email, level, notes
 
-        return {
+        returns {
-            'status': {'code': int, 'text': string}
-            'data': {
-            }
         }
     '''
     response = json_response()
@@ -377,14 +358,10 @@ actions.register(editUser, cache=False)
 @admin_required_json
 def removeUser(request):
     '''
-        param data {
+        takes {
             username: username
         }
-        return {
+        returns {}
-            'status': {'code': int, 'text': string}
-            'data': {
-            }
-        }
     '''
     response = json_response()
     data = json.load(request.POST['data'])
@@ -395,18 +372,15 @@ actions.register(removeUser, cache=False)
 
 def findUser(request):
     '''
-        param data {
+        takes {
-            key: "username",
+            key: string, //username, email
-            value: "foo",
+            value: string,
-            operator: "=="
+            operator: "==" // "==", "="
-            keys: []
+            keys: [string]
         }
 
-        return {
+        returns {
-            'status': {'code': int, 'text': string}
+            users: [object]
-            'data': {
-                users = [{username: 'user1', level: ...}, {username: 'user2', ..}]
-            }
         }
     '''
     data = json.loads(request.POST['data'])
@@ -468,7 +442,7 @@ def order_query(qs, sort):
 @admin_required_json
 def findUsers(request):
     '''
-        param data {
+        takes {
             query: {
                 conditions: [
                     {
@@ -487,19 +461,17 @@ def findUsers(request):
         possible query keys:
             username, email, lastLogin, browser
         
-        return {
+        returns {
-                status: {
-                    code: int,
-                    text: string
-                },
-                data: {
             items: [
                 {name:, user:, featured:, public...}
             ]
         }
+
+        takes {
+            query: query,
+            sort: array,
+            range: array
         }
-        param data
-            {'query': query, 'sort': array, 'range': array}
 
             query: query object, more on query syntax at
                    https://wiki.0x2620.org/wiki/pandora/QuerySyntax
@@ -517,12 +489,15 @@ def findUsers(request):
             range:       result range, array [from, to]
 
         with keys, items is list of dicts with requested properties:
-          return {'status': {'code': int, 'text': string},
+        returns {
-                'data': {items: array}}
+            items: [object]
+        }
 
 Positions
-        param data
+        takes {
-            {'query': query, 'positions': []}
+            query: query,
+            positions: []
+        }
 
             query: query object, more on query syntax at
                    https://wiki.0x2620.org/wiki/pandora/QuerySyntax
@@ -560,18 +535,17 @@ actions.register(findUsers)
 @login_required_json
 def mail(request):
     '''
-        param data {
+        takes {
-            'to': array of usernames,
+            to: [string], // array of usernames to send mail to
-            'subject': string,
+            subject: string,
-            'message': string
+            message: string
         }
 
         message can contain {username} or {email},
         this will be replace with the user/email
         the mail is sent to.
 
-        return {
+        returns {
-            'status': {'code': int, 'text': string}
         }
     '''
     response = json_response()
@@ -625,14 +599,13 @@ actions.register(mail, cache=False)
 
 def contact(request):
     '''
-        param data {
+        takes {
-            'email': string,
+            email: string,
-            'subject': string,
+            subject: string,
-            'message': string
+            message: string
         }
 
-        return {
+        returns {
-            'status': {'code': int, 'text': string}
         }
     '''
     data = json.loads(request.POST['data'])
@@ -699,11 +672,11 @@ def getPositionById(list, key):
 @login_required_json
 def editPreferences(request):
     '''
-        param data {
+        takes {
             key: value
         }
         keys: email, password
-        return
+        returns {}
     '''
     data = json.loads(request.POST['data'])
     errors = {}
@@ -743,11 +716,10 @@ def reset_ui(request):
 def resetUI(request):
     '''
         reset user ui settings to defaults
-        param data {
+        takes {
         }
 
-        return {
+        returns {
-            'status': {'code': int, 'text': string}
         }
     '''
     response = json_response()
@@ -762,14 +734,13 @@ actions.register(resetUI, cache=False)
 
 def setUI(request):
     '''
-        param data {
+        takes {
             key.subkey: value
         }
         you can set nested keys
             api.setUI({"lists|my|ListView": "icons"})
 
-        return {
+        returns {
-            'status': {'code': int, 'text': string}
         }
     '''
     data = json.loads(request.POST['data'])

static/js/pandora/apiDialog.js

@@ -142,7 +142,7 @@ pandora.ui.apiDialog = function() {
                 .appendTo($text);
 
             Ox.Button({
-                    title: 'View Source (' + f + ')',
+                    title: 'Source (' + f + ')',
                 }).bindEvent({
                     click: function() {
                         $code.toggle();
@@ -159,7 +159,7 @@ pandora.ui.apiDialog = function() {
             })
             .css({
                 borderWidth: '1px',
-            }).appendTo($text).hide();
+            }).appendTo($text);
         } else {
             $text.html(overview);
         }