From e706fbfb9befdd6b3cba91321524e6bbf1255aae Mon Sep 17 00:00:00 2001 From: j <0x006A@0x2620.org> Date: Mon, 4 Mar 2013 19:35:06 +0000 Subject: [PATCH] api documentation takes and returns --- pandora/annotation/views.py | 44 +++---- pandora/app/views.py | 41 +++---- pandora/archive/views.py | 122 ++++++++----------- pandora/clip/views.py | 21 ++-- pandora/edit/views.py | 70 +++++------ pandora/event/views.py | 74 ++++++------ pandora/item/views.py | 208 ++++++++++++++------------------- pandora/itemlist/views.py | 74 ++++-------- pandora/log/views.py | 30 +++-- pandora/news/views.py | 53 +++++---- pandora/person/views.py | 44 ++++--- pandora/place/views.py | 81 ++++++------- pandora/sequence/views.py | 24 ++-- pandora/text/views.py | 73 +++++------- pandora/title/views.py | 34 +++--- pandora/tv/views.py | 11 ++ pandora/user/views.py | 203 ++++++++++++++------------------ static/js/pandora/apiDialog.js | 4 +- 18 files changed, 527 insertions(+), 684 deletions(-) diff --git a/pandora/annotation/views.py b/pandora/annotation/views.py index 3a632266..5d529497 100644 --- a/pandora/annotation/views.py +++ b/pandora/annotation/views.py @@ -64,7 +64,7 @@ def order_query(qs, sort): def findAnnotations(request): ''' - param data { + takes { query: { conditions: [], operator: '&' @@ -79,11 +79,8 @@ def findAnnotations(request): range: [in, out], sort: [] } - return { - 'status': {'code': int, 'text': string} - 'data': { - annotations = [{..}, {...}, ...] - } + returns { + annotations = [{..}, {...}, ...] } ''' data = json.loads(request.POST['data']) @@ -117,18 +114,16 @@ 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}, - 'data': { - id: 123, //id of new annotation - ... - } + returns { + id: string, //id of new annotation + ... } ''' data = json.loads(request.POST['data']) @@ -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}, - 'data': { - id: 123, //id of new annotation - ... - } + returns { + taskId: string } ''' 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}, - 'data': { - } + returns { } ''' response = json_response({}) @@ -223,17 +213,15 @@ 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}, - 'data': { - id: - ... - } + returns { + id: + ... } ''' response = json_response({}) diff --git a/pandora/app/views.py b/pandora/app/views.py index 5601b095..4a56c5b3 100644 --- a/pandora/app/views.py +++ b/pandora/app/views.py @@ -95,15 +95,12 @@ def robots_txt(request, url): def getPage(request): ''' - param data { + takes { name: pagename } - return { - status: ... - data: { - name: - text: - } + returns { + name: + text: } ''' data = json.loads(request.POST['data']) @@ -123,16 +120,13 @@ actions.register(getPage) @login_required_json def editPage(request): ''' - param data { + takes { name: pagename text: text } - return { - status: ... - data: { - name: - text: - } + returns { + name: + text: } ''' if request.user.get_profile().capability('canEditSitePages'): @@ -151,8 +145,10 @@ actions.register(editPage) def init(request): ''' - return {'status': {'code': int, 'text': string}, - 'data': {user: object}} + takes {} + 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 { - status: ... - data: { - html - ... - } + returns { + html + ... } - return {'status': {'code': int, 'text': string}, - 'data': {user: object}} ''' data = json.loads(request.POST['data']) response = json_response({}) diff --git a/pandora/archive/views.py b/pandora/archive/views.py index d0ba76cc..626c2647 100644 --- a/pandora/archive/views.py +++ b/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,13 +60,10 @@ def update(request): info: {oshash: object} } - return { - 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 - } + returns { + 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']) @@ -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,16 +116,15 @@ actions.register(update, cache=False) @login_required_json def upload(request): ''' - id: string - frame: [] //multipart frames - file: [] //multipart file + takes { + id: string + frame: [] //multipart frames + file: [] //multipart file + } - return { - status: {'code': int, 'text': string}, - data: { - info: object, - rename: object - } + returns { + info: object, + rename: object } ''' response = json_response({}) @@ -174,14 +168,13 @@ class VideoChunkForm(forms.Form): @login_required_json def addFile(request): ''' - id: oshash - title: - info: {} - return { - status: {'code': int, 'text': string}, - data: { - item: id, - } + takes { + id: oshash + title: + info: {} + } + 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 { - status: {'code': int, 'text': string}, - data: { - } + returns { } ''' 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 { - status: {'code': int, 'text': string}, - data: { - } + returns { } ''' data = json.loads(request.POST['data']) @@ -419,15 +406,12 @@ actions.register(removeFiles, cache=False) def getPath(request): ''' change file / item link - param data { + takes { id: [hash of file] } - return { - status: {'code': int, 'text': string}, - data: { - id: path - } + returns { + id: path } ''' data = json.loads(request.POST['data']) @@ -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}, - 'data': {items: array}} + returns { + items: [object] + } Groups - param data { + takes { 'query': query, 'key': string, 'group': string, @@ -522,28 +507,27 @@ Groups with keys items contains list of {'path': string, 'items': int}: - return {'status': {'code': int, 'text': string}, - 'data': {items: array}} + returns { + items: [object] + } without keys: return number of items in given query - return {'status': {'code': int, 'text': string}, - 'data': {items: int}} + returns { + 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 { - status: {...}, - data: { - positions: { - id: position - } + returns { + positions: { + id: position } } ''' @@ -613,14 +597,11 @@ actions.register(findFiles) def parsePath(request): #parse path and return info ''' - param data { + takes { path: string } - return { - status: {'code': int, 'text': string}, - data: { - imdb: string - } + returns { + imdb: string } ''' path = json.loads(request.POST['data'])['path'] @@ -630,15 +611,12 @@ actions.register(parsePath) def getFileInfo(request): ''' - param data { + takes { id: oshash of stream file } - return { - status: {'code': int, 'text': string}, - data: { - item: itemId, - file: oshash of source file - } + returns { + item: itemId, + file: oshash of source file } ''' data = json.loads(request.POST['data']) diff --git a/pandora/clip/views.py b/pandora/clip/views.py index 0c89ab53..edf9f8d4 100644 --- a/pandora/clip/views.py +++ b/pandora/clip/views.py @@ -73,27 +73,24 @@ def order_query(qs, sort): def findClips(request): ''' - param data { + takes { query: { - conditions: [], - operator: '&' + conditions: [object], + operator: string // '&' or '|' }, itemsQuery: { conditions: [], - operator: '&' + operator: string // '&' or '|' }, - keys: [], + keys: [string], position: int, - positions: [], - range: [in, out], + positions: [string], + range: [int, int], sort: [] } - return { - 'status': {'code': int, 'text': string} - 'data': { - items = [{..}, {...}, ...] - } + returns { + items: [object] } ''' data = json.loads(request.POST['data']) diff --git a/pandora/edit/views.py b/pandora/edit/views.py index 2a442aa3..46bdf725 100644 --- a/pandora/edit/views.py +++ b/pandora/edit/views.py @@ -13,14 +13,14 @@ import models @login_required_json def addClip(request): ''' - param data - {timeline: timelineId, - item: itemId, - start: float, - end: float, - } - return {'status': {'code': int, 'text': string}, - 'data': {}} + takes { + item: string, + edit: string, + start: float, + end: float, + } + returns { + } ''' 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 - {timeline: timelineId, - clip: clipId, - } - return {'status': {'code': int, 'text': string}, - 'data': {}} + takes { + item: string + } + returns { + } ''' 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 - {name: value, user: user} - return { - 'status': {'code': int, 'text': string}, - 'data': { - fixme - } + takes { + name: string, + user: string + } + returns { + ... } could be @@ -107,10 +105,12 @@ actions.register(getTimeline) @login_required_json def addTimeline(request): ''' - param data - {name: value} - return {'status': {'code': int, 'text': string}, - 'data': {}} + takes { + ... + } + 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 - {key: value} - keys: name, public - return {'status': {'code': int, 'text': string}, - 'data': {} + takes { + ... + } + returns { + ... } ''' data = json.loads(request.POST['data']) @@ -151,10 +151,12 @@ actions.register(editTimeline, cache=False) @login_required_json def removeTimeline(request): ''' - param data - {key: value} - return {'status': {'code': int, 'text': string}, - 'data': {}} + takes { + ... + } + returns { + ... + } ''' data = json.loads(request.POST['data']) list = get_object_or_404_json(models.Timeline, pk=data['list']) diff --git a/pandora/event/views.py b/pandora/event/views.py index d33bc584..31982a38 100644 --- a/pandora/event/views.py +++ b/pandora/event/views.py @@ -18,13 +18,14 @@ import models @login_required_json def addEvent(request): ''' - param data - { - 'name': '', - 'start': '' - 'end': '' - } - required keys: name, start, end + takes { + name: string, + start: string, + end: string + } + returns { + id: string + } ''' 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 - { - 'id': event id, - 'name': '' - ... - } - update provides keys of event with id + takes { + id: string, + name: string, + start: string, + end: string + } + returns { + id: string, + ... + } ''' 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 - {'query': query, 'sort': array, 'range': array} + takes { + query: object, + sort: array + range': [int, int] + } query: query object, more on query syntax at https://wiki.0x2620.org/wiki/pandora/QuerySyntax @@ -188,16 +195,17 @@ 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 - {'query': query, 'ids': []} - - query: query object, more on query syntax at - https://wiki.0x2620.org/wiki/pandora/QuerySyntax - ids: ids of events for which positions are required + takes { + 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 ''' response = json_response(status=200, text='ok') @@ -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({}) diff --git a/pandora/item/views.py b/pandora/item/views.py index d66ba597..859089e9 100644 --- a/pandora/item/views.py +++ b/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}, - 'data': {items: array}} + returns { + 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}, - 'data': {items: array}} + returns { + items: [objects] + } without keys: return number of items in given query - return {'status': {'code': int, 'text': string}, - 'data': {items: int}} + returns { + items: int + } Positions - param data { + takes { 'query': query, 'positions': [], 'sort': array @@ -168,12 +171,9 @@ 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 { - status: {...}, - data: { - positions: { - id: position - } + returns { + positions: { + id: position } } ''' @@ -298,15 +298,16 @@ actions.register(find) def autocomplete(request): ''' - param data - key - value - operator '=', '==', '^', '$' - query - range - return - - query can be an item query to limit results + takes { + key: string, + value: string, + operator: string // '=', '==', '^', '$' + query: object // item query to limit results + range: [int, int] + } + returns { + 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 { - 'id': - 'title': - 'director': [] - 'year': ... + takes { + 'id': string + 'title': string + 'director': [string] + '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 { - title: '', - director: [], + takes { + title: string, + 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 { - id: string - keys: array + takes { + id: string, + keys: [string] + } + returns { + key: value } - return item array ''' response = json_response({}) data = json.loads(request.POST['data']) @@ -481,15 +488,13 @@ actions.register(get) @login_required_json def add(request): ''' - param data { + takes { + title: string, //(optional) } - return { - status: {'code': int, 'text': string}, - data: { - id: - name: - ... - } + returns { + id: + name: + ... } ''' @@ -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 { - status: {'code': int, 'text': string}, - data: {} + returns { + key: value + .. } ''' 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) -''' - Poster API -''' - - -def setPosterFrame(request): #parse path and return info +def setPosterFrame(request): ''' - param data { - id: itemId, + takes { + id: string, position: float } - return { - status: {'code': int, 'text': string}, - data: { - } + returns { } ''' 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 { - id: itemId, - source: string + takes { + id: string, + source: string // url } - return { - status: {'code': int, 'text': string}, - data: { - poster: {url,width,height} + returns { + poster: { + url: string, + width: int, + height: int } } ''' @@ -645,14 +650,10 @@ actions.register(setPoster, cache=False) def updateExternalData(request): ''' - param data { - id: itemId, + takes { + id: string, } - return { - status: {'code': int, 'text': string}, - data: { - poster: {url,width,height} - } + returns { } ''' data = json.loads(request.POST['data']) @@ -667,20 +668,17 @@ actions.register(updateExternalData, cache=False) def lookup(request): ''' - param data { + takes { title: string, director: [string], year: string, id: string } - return { - status: {'code': int, 'text': string}, - data: { - title: string, - director: [string], - year: string, - id: string - } + returns { + title: string, + director: [string], + year: string, + id: string } ''' data = json.loads(request.POST['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): diff --git a/pandora/itemlist/views.py b/pandora/itemlist/views.py index f17f6c00..73b64732 100644 --- a/pandora/itemlist/views.py +++ b/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}, - data: { - items: [ - {name:, user:, featured:, public...} - ] - } + returns { + items: [{name: string, user: string, featured: bool, 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 { - status: {'code': int, 'text': string}, - data: { - } + returns { } ''' 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 { - status: {'code': int, 'text': string}, - data: { - } + returns { } ''' 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,13 +191,10 @@ def addList(request): view sort - return { - status: {'code': int, 'text': string}, - data: { - id: - name: - ... - } + returns { + id: string, + name: string, + ... } ''' data = json.loads(request.POST['data']) @@ -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 { - status: {'code': int, 'text': string}, - data: { - } + returns { + id: string, + ... } ''' 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 { - status: {'code': int, 'text': string}, - data: { - } + returns { } ''' 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 { - status: {'code': int, 'text': string}, - data: { - } + returns { } ''' 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 { - status: {'code': int, 'text': string}, - data: { - } + returns { } ''' 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 { - status: {'code': int, 'text': string}, - data: { - } + returns { } ''' data = json.loads(request.POST['data']) diff --git a/pandora/log/views.py b/pandora/log/views.py index 8da3a632..19520bb4 100644 --- a/pandora/log/views.py +++ b/pandora/log/views.py @@ -17,17 +17,12 @@ import models def log(request): ''' - param data { - url: url - line: line - text: text + takes { + url: string, + line: string, + 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 { - 'ids': , + takes { + 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] - keys: [] + range: [int, int] + keys: [string] + } + returns { + items: [object] } ''' diff --git a/pandora/news/views.py b/pandora/news/views.py index 49229200..84f292e3 100644 --- a/pandora/news/views.py +++ b/pandora/news/views.py @@ -14,14 +14,20 @@ import models def getNews(request): ''' - param data { + takes { + id: string } - return { - 'status': {'code': int, 'text': string} - 'data': { - items = [{..}, {...}, ...] - } + returns { + id: string, + ... + } + + if not id is passed, return all news items + + takes {} + returns { + items: [object] } ''' data = json.loads(request.POST['data']) @@ -38,16 +44,14 @@ actions.register(getNews) @login_required_json def addNews(request): ''' - param data { + takes { title: string, date: string, text: text, } - return {'status': {'code': int, 'text': string}, - 'data': { - id: 123, - ... - } + returns { + id: string, + ... } ''' 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}, - 'data': { - } - } + returns {} ''' data = json.loads(request.POST['data']) response = json_response({}) @@ -86,17 +87,15 @@ actions.register(removeNews, cache=False) @login_required_json def editNews(request): ''' - param data { - id:, - title: - text: - date: + takes { + id: string, + title: string, + text: string, + date: string } - return {'status': {'code': int, 'text': string}, - 'data': { - id: - ... - } + returns { + id: string + ... } ''' response = json_response({}) diff --git a/pandora/person/views.py b/pandora/person/views.py index df91c23f..1d468be2 100644 --- a/pandora/person/views.py +++ b/pandora/person/views.py @@ -17,11 +17,15 @@ import tasks @admin_required_json def editName(request): ''' - param data { - 'id': nameid, - 'sortname': ... + takes { + id: id, + 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 { - 'name': name - or - 'names': [name, name] + get sort name(s) for given name or names + takes { + names: [string] + 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 { - status: { - code: int, - text: string - }, - data: { - items: [ - {name:, user:, featured:, public...} - ] - } + returns { + 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}, - 'data': {items: array}} - + returns { + items: [string] + } ''' data = json.loads(request.POST['data']) response = json_response() diff --git a/pandora/place/views.py b/pandora/place/views.py index 14f8d680..657c6fa0 100644 --- a/pandora/place/views.py +++ b/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 { - 'id': placeid, - 'name': ... - 'north': 0... + takes { + id: string, + name: string + 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 { - 'id': placeid, + takes { + 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] - keys: [] + range: [int, int] + keys: [string] } possible query keys: @@ -233,20 +239,14 @@ def findPlaces(request): possible keys: name, geoname, user - return { - status: { - code: int, - text: string - }, - data: { - items: [ - {name:, user:, featured:, public...} - ] - } + returns { + items: [object] + } + 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,16 +263,18 @@ 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}, - 'data': {items: array}} + returns { + items: [string] + } Positions - param data - {'query': query, 'positions': []} - - query: query object, more on query syntax at - https://wiki.0x2620.org/wiki/pandora/QuerySyntax - positions: ids of places for which positions are required + takes { + 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 ''' data = json.loads(request.POST['data']) response = json_response() @@ -311,18 +313,9 @@ actions.register(findPlaces) def getPlaceNames(request): ''' - param data { - } - return { - status: { - code: int, - text: string - }, - data: { - items: [ - {name:, matches} - ] - } + takes {} + returns { + items: [{name: string, matches: int}] } ''' response = json_response({}) diff --git a/pandora/sequence/views.py b/pandora/sequence/views.py index d1d103df..ffa5411f 100644 --- a/pandora/sequence/views.py +++ b/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 { - 'status': {'code': int, 'text': string} - 'data': { - items = [{..}, {...}, ...] - } + returns { + items: [object] } ''' data = json.loads(request.POST['data']) @@ -96,20 +93,17 @@ actions.register(findSequences) def getSequence(request): ''' - param data { + takes { id mode position } - return { - 'status': {'code': int, 'text': string} - 'data': { - id - mode - in - out - } + returns { + id + mode + in + out } ''' data = json.loads(request.POST['data']) diff --git a/pandora/text/views.py b/pandora/text/views.py index dd2ca768..3e693012 100644 --- a/pandora/text/views.py +++ b/pandora/text/views.py @@ -27,16 +27,13 @@ def get_text_or_404_json(id): @login_required_json def addText(request): ''' - param data { + takes { name: value, } - return { - status: {'code': int, 'text': string}, - data: { - id: - name: - ... - } + returns { + id: + name: + ... } ''' data = json.loads(request.POST['data']) @@ -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}, - data: { - items: [ - {name:, user:, featured:, public...} - ] - } + returns { + items: [object] } ''' data = json.loads(request.POST['data']) @@ -248,13 +241,10 @@ actions.register(findTexts) @login_required_json def removeText(request): ''' - param data { - id: testId, + takes { + 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 { - id: testId, - } - return { - status: {'code': int, 'text': string}, - data: { - } + takes { + id: string, } + 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 { - id: testId, + takes { + id: string, user: username(only admins) } - return { - status: {'code': int, 'text': string}, - data: { - } - } + returns {} ''' 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}, - data: { - } - } + known sections: 'personal', 'public', 'featured' + featured can only be edited by admins + + returns {} ''' data = json.loads(request.POST['data']) position = 0 diff --git a/pandora/title/views.py b/pandora/title/views.py index 6b7a4f09..f8564ae1 100644 --- a/pandora/title/views.py +++ b/pandora/title/views.py @@ -17,11 +17,14 @@ import models @admin_required_json def editTitle(request): ''' - param data { - 'id': titleid, - 'sorttitle': ... + takes { + id: string + 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 { - status: { - code: int, - text: string - }, - data: { - items: [ - {title:, user:, featured:, public...} - ] - } + returns { + items: [object] + } + + 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}, - 'data': {items: array}} + returns {items: [object]} ''' data = json.loads(request.POST['data']) diff --git a/pandora/tv/views.py b/pandora/tv/views.py index f991c0ce..c54dbf70 100644 --- a/pandora/tv/views.py +++ b/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']) diff --git a/pandora/user/views.py b/pandora/user/views.py index e7a0c912..065cb519 100644 --- a/pandora/user/views.py +++ b/pandora/user/views.py @@ -25,21 +25,18 @@ import models def signin(request): ''' - param data { - username: 'username', - password: 'password' + takes { + username: string, + password: string } - return { - status: {'code': 200, 'text': 'ok'} - data: { - errors: { - username: 'Unknown Username', - password: 'Incorrect Password' - } - user: { - ... - } + returns { + errors: { + username: 'Unknown Username', + password: 'Incorrect Password' + } + user: { + ... } } ''' @@ -84,15 +81,11 @@ actions.register(signin, cache=False) def signout(request): ''' - param data { - } + takes {} - return { - status: {'code': int, 'text': string} - data: { - user: { - default user - } + returns { + user: { + default user } } ''' @@ -112,22 +105,19 @@ actions.register(signout, cache=False) def signup(request): ''' - param data { - username: 'username', - password: 'password', - email: 'emailaddress' + takes { + username: string, + password: string, + email: string } - return { - status: {'code': int, 'text': string} - data: { - errors: { - username: 'Unknown Username', - password: 'Incorrect Password' - } - user: { - ... - } + returns { + errors: { + username: 'Unknown Username', + password: 'Incorrect Password' + } + user: { + ... } } ''' @@ -196,20 +186,17 @@ actions.register(signup, cache=False) def resetPassword(request): ''' - param data { - username: username, - password: new password - code: reset code + takes { + username: string, + password: string, + code: string } - return { - status: {'code': int, 'text': string} - data: { - errors: { - code: 'Incorrect Code' - } - user { - } + returns { + errors: { + code: 'Incorrect Code' + } + user { } } ''' @@ -252,20 +239,17 @@ actions.register(resetPassword, cache=False) def requestToken(request): ''' - param data { - username: username, - email: email + takes { + username: string, + email: string } - return { - status: {'code': int, 'text': string} - data: { - errors: { - username: 'Unknown Username' - email: 'Unknown Email' - } - username: user + returns { + errors: { + username: 'Unknown Username' + email: 'Unknown Email' } + username: user } ''' data = json.loads(request.POST['data']) @@ -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 { - 'status': {'code': int, 'text': string} - 'data': { - } + returns { } ''' response = json_response() @@ -377,14 +358,10 @@ actions.register(editUser, cache=False) @admin_required_json def removeUser(request): ''' - param data { + takes { username: username } - return { - 'status': {'code': int, 'text': string} - 'data': { - } - } + returns {} ''' response = json_response() data = json.load(request.POST['data']) @@ -395,18 +372,15 @@ actions.register(removeUser, cache=False) def findUser(request): ''' - param data { - key: "username", - value: "foo", - operator: "==" - keys: [] + takes { + key: string, //username, email + value: string, + operator: "==" // "==", "=" + keys: [string] } - return { - 'status': {'code': int, 'text': string} - 'data': { - users = [{username: 'user1', level: ...}, {username: 'user2', ..}] - } + returns { + users: [object] } ''' 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 { - status: { - code: int, - text: string - }, - data: { - items: [ - {name:, user:, featured:, public...} - ] - } + returns { + 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}, - 'data': {items: array}} + returns { + items: [object] + } Positions - param data - {'query': query, 'positions': []} + takes { + 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 { - 'to': array of usernames, - 'subject': string, - 'message': string + takes { + to: [string], // array of usernames to send mail to + subject: string, + message: string } message can contain {username} or {email}, this will be replace with the user/email the mail is sent to. - return { - 'status': {'code': int, 'text': string} + returns { } ''' response = json_response() @@ -625,14 +599,13 @@ actions.register(mail, cache=False) def contact(request): ''' - param data { - 'email': string, - 'subject': string, - 'message': string + takes { + email: string, + subject: string, + message: string } - return { - 'status': {'code': int, 'text': string} + returns { } ''' 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 { - 'status': {'code': int, 'text': string} + returns { } ''' 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 { - 'status': {'code': int, 'text': string} + returns { } ''' data = json.loads(request.POST['data']) diff --git a/static/js/pandora/apiDialog.js b/static/js/pandora/apiDialog.js index 62858124..08438cae 100644 --- a/static/js/pandora/apiDialog.js +++ b/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); }