From 0a56268b9262e2ce2cc11d2728b44a2519287e1d Mon Sep 17 00:00:00 2001 From: rolux Date: Thu, 18 Dec 2014 19:26:37 +0000 Subject: [PATCH] update api docs --- pandora/edit/views.py | 5 +- pandora/entity/views.py | 110 ++++++++++---------- pandora/event/views.py | 73 +++++++------ pandora/item/views.py | 4 + pandora/itemlist/views.py | 211 +++++++++++++++++++------------------- pandora/place/views.py | 173 ++++++++++++++++--------------- 6 files changed, 299 insertions(+), 277 deletions(-) diff --git a/pandora/edit/views.py b/pandora/edit/views.py index 7fb46f9b..b8d6a65f 100644 --- a/pandora/edit/views.py +++ b/pandora/edit/views.py @@ -45,8 +45,9 @@ def addClips(request, data): ] } returns {} - notes: Clips are either {item, in, out} or {annotation}. If index is - missing, clips will be inserted at the end of the edit. + notes: Clips are either {item, in, out} (by value) or {annotation} (by + reference). If `index` is missing, clips will be inserted at the end of the + edit. see: editClip, orderClips, removeClips, sortClips ''' response = json_response() diff --git a/pandora/entity/views.py b/pandora/entity/views.py index bebd01af..d3400008 100644 --- a/pandora/entity/views.py +++ b/pandora/entity/views.py @@ -31,14 +31,14 @@ def get_entity_or_404_json(id): @login_required_json def addEntity(request, data): ''' - add entity - takes { - type: - name: - alternativeNames - } - returns { - } + Adds an entity + takes { + type: string, + name: string, + alternativeNames: [string] + } + returns {} + see: editEntity, findEntities, getEntity, removeEntity ''' existing_names = [] exists = False @@ -97,6 +97,7 @@ def autocompleteEntities(request, data): returns { items: [{id, name,...}, ...] // array of matching entities } + see: autocomplete ''' if not 'range' in data: data['range'] = [0, 10] @@ -144,16 +145,18 @@ actions.register(autocompleteEntities) @login_required_json def editEntity(request, data): ''' - takes { - id: string - name: string - description: string - item(optional): edit descriptoin per item - } - returns { - id: - ... - } + Edits an entity + takes { + id: string + name: string + description: string + item(optional): edit descriptoin per item + } + returns { + id: + ... + } + see: addEntity, findEntities, getEntity, removeEntity ''' response = json_response() entity = get_entity_or_404_json(data['id']) @@ -197,32 +200,25 @@ def parse_query(data, user): def findEntities(request, data): ''' - takes { - query: { - conditions: [ - { - key: 'name', - value: 'something', - operator: '=' - } - ] - operator: "," - }, - sort: [{key: 'name', operator: '+'}], - range: [0, 100] - keys: [] - } + Finds entities for a given query + takes { + query: object, // query object, see `find` + sort: [object], // list of sort objects, see `find` + range: [int, int], // range of results + keys: [string] // list of properties to return + } - possible query keys: - name, type + possible query keys: + name, type - possible keys: - name, type, alternativeNames + possible keys: + name, type, alternativeNames - } - returns { - items: [object] - } + } + returns { + items: [object] + } + see: addEntity, editEntity, getEntity, removeEntity ''' query = parse_query(data, request.user) @@ -246,13 +242,15 @@ actions.register(findEntities) def getEntity(request, data): ''' - takes { - id: string, - keys: [string] - } - returns { - key: value - } + Gets an entity by id + takes { + id: string, + keys: [string] + } + returns { + key: value + } + see: addEntity, editEntity, findEntities, removeEntity ''' response = json_response({}) data['keys'] = data.get('keys', []) @@ -264,13 +262,15 @@ actions.register(getEntity) @login_required_json def removeEntity(request, data): ''' - takes { - id: string, - or - ids: [string] - } - returns { - } + Removes an entity + takes { + id: string, + or + ids: [string] + } + returns { + } + see: addEntity, editEntity, findEntities, getEntity ''' response = json_response() diff --git a/pandora/event/views.py b/pandora/event/views.py index 63bc8fc3..36c4305a 100644 --- a/pandora/event/views.py +++ b/pandora/event/views.py @@ -19,14 +19,16 @@ import models @login_required_json def addEvent(request, data): ''' - takes { - name: string, - start: string, - end: string - } - returns { - id: string - } + Adds a calendar event + takes { + name: string, + start: string, + end: string + } + returns { + id: string + } + see: editEvent, findEvents, removeEvents ''' existing_names = [] exists = False @@ -69,16 +71,18 @@ actions.register(addEvent, cache=False) @login_required_json def editEvent(request, data): ''' - takes { - id: string, - name: string, - start: string, - end: string - } - returns { - id: string, - ... - } + Edits a calendar event + takes { + id: string, + name: string, + start: string, + end: string + } + returns { + id: string, + ... + } + see: addEvent, findEvents, removeEvent ''' event = get_object_or_404_json(models.Event, pk=ox.fromAZ(data['id'])) if event.editable(request.user): @@ -123,11 +127,12 @@ actions.register(editEvent, cache=False) @login_required_json def removeEvent(request, data): ''' - remove Event with given id - takes { - id: event id - } - returns {} + Removes a calendar event + takes { + id: event id + } + returns {} + see: addEvent, editEvent, findEvents ''' event = get_object_or_404_json(models.Event, pk=ox.fromAZ(data['id'])) if event.editable(request.user): @@ -169,11 +174,12 @@ def order_query(qs, sort): def findEvents(request, data): ''' - takes { - query: object, - sort: array - range': [int, int] - } + Finds calendar events + takes { + query: object, + sort: array + range': [int, int] + } query: query object, more on query syntax at https://wiki.0x2620.org/wiki/pandora/QuerySyntax @@ -238,11 +244,12 @@ actions.register(findEvents) def getEventNames(request, data): ''' - takes { - } - returns { - items: [{name: string, matches: int}] - } + Undocumented + takes { + } + returns { + items: [{name: string, matches: int}] + } ''' response = json_response({}) layers = [l['id'] for l in filter(lambda l: l['type'] == 'event', diff --git a/pandora/item/views.py b/pandora/item/views.py index 2165c0b8..cefd2878 100644 --- a/pandora/item/views.py +++ b/pandora/item/views.py @@ -160,6 +160,10 @@ def find(request, data): notes: Comparison operators are '=' (contains) '==' (is), '^' (starts with), '$' (ends with), '<', '<=', '>', or '>=', each optionally prefixed with '!' (not). + Leaving out `keys` or passing `positions` can be useful when building a + responsive GUI: First leave out `keys` to get totals as fast as possible, + then pass `positions` to get the positions of previously selected items, + finally make the query with `keys` and an appropriate range. see: add, edit, get, lookup, remove, upload ''' if settings.JSON_DEBUG: diff --git a/pandora/itemlist/views.py b/pandora/itemlist/views.py index 7e984203..573cdec3 100644 --- a/pandora/itemlist/views.py +++ b/pandora/itemlist/views.py @@ -58,32 +58,24 @@ def parse_query(data, user): def findLists(request, data): ''' - takes { - query: { - conditions: [ - { - key: 'user', - value: 'something', - operator: '=' - } - ] - operator: "," - }, - sort: [{key: 'name', operator: '+'}], - range: [0, 100] - keys: [] - } + takes { + query: object, // query object, see `find` + sort: [], // list of sort objects, see `find` + range: [int, int], // range of results + keys: [string] // properties to return + } - possible query keys: - name, user, featured, subscribed + possible query keys: + name, user, featured, subscribed - possible keys: - name, user, featured, subscribed, query + possible keys: + name, user, featured, subscribed, query - } - returns { - items: [{name: string, user: string, featured: bool, public...}] - } + } + returns { + items: [{name: string, user: string, featured: bool, public...}] + } + see: addList, editList, getList, removeList, sortLists ''' query = parse_query(data, request.user) @@ -121,14 +113,16 @@ actions.register(findLists) def getList(request, data): ''' - takes { - id: listid - } - returns { - id: - section: - ... - } + Gets a list by id + takes { + id: listid + } + returns { + id: + section: + ... + } + see: addList, editList, findLists, removeList, sortLists ''' if 'id' in data: response = json_response() @@ -145,13 +139,14 @@ actions.register(getList) @login_required_json def addListItems(request, data): ''' - takes { - list: listId, - items: [itemId], - query: ... - } - returns { - } + Adds one or more items to a list + takes { + list: listId, + items: [itemId], + query: ... + } + returns { + } ''' list = get_list_or_404_json(data['list']) if 'items' in data: @@ -174,13 +169,14 @@ actions.register(addListItems, cache=False) @login_required_json def removeListItems(request, data): ''' - takes { - list: listId, - items: [itemId], - quert: ... - } - returns { - } + Removes one or more items from a list + takes { + list: listId, + items: [itemId], + quert: ... + } + returns { + } ''' list = get_list_or_404_json(data['list']) if 'items' in data: @@ -201,12 +197,14 @@ actions.register(removeListItems, cache=False) @login_required_json def orderListItems(request, data): ''' - takes { - list: string - ids: [string] - } - returns { - } + Sets the manual order of items in a given list + takes { + list: string + ids: [string] + } + returns { + } + notes: There is no UI for this yet. ''' list = get_list_or_404_json(data['list']) response = json_response() @@ -225,23 +223,25 @@ actions.register(orderListItems, cache=False) @login_required_json def addList(request, data): ''' - takes { - name: value, - } - possible keys to create list: - name - description - type - query - items - view - sort + Adds a new list + takes { + name: value, + } + possible keys to create list: + name + description + type + query + items + view + sort - returns { - id: string, - name: string, - ... - } + returns { + id: string, + name: string, + ... + } + see: editList, findLists, getList, removeList, sortLists ''' data['name'] = re.sub(' \[\d+\]$', '', data.get('name', 'Untitled')).strip() name = data['name'] @@ -285,19 +285,21 @@ actions.register(addList, cache=False) @login_required_json def editList(request, data): ''' - takes { - id: listId, - key: value, - } - keys: name, status, query, position, posterFrames - if you change status you have to provide position of list + Edits a list + takes { + id: listId, + key: value, + } + keys: name, status, query, position, posterFrames + if you change status you have to provide position of list - posterFrames: - array with objects that have item/position - returns { - id: string, - ... - } + posterFrames: + array with objects that have item/position + returns { + id: string, + ... + } + see: addList, findLists, getList, removeList, sortLists ''' list = get_list_or_404_json(data['id']) if list.editable(request.user): @@ -313,11 +315,12 @@ actions.register(editList, cache=False) @login_required_json def removeList(request, data): ''' - takes { - id: listId, - } - returns { - } + Removes a list + takes { + id: string // list id + } + returns {} + see: addList, editList, findLists, getList, sortLists ''' list = get_list_or_404_json(data['id']) response = json_response() @@ -334,11 +337,12 @@ actions.register(removeList, cache=False) @login_required_json def subscribeToList(request, data): ''' - takes { - id: listId, - } - returns { - } + Adds a list to favorites + takes { + id: listId, + } + returns {} + see: unsubscribeFromList ''' list = get_list_or_404_json(data['id']) user = request.user @@ -359,12 +363,13 @@ actions.register(subscribeToList, cache=False) @login_required_json def unsubscribeFromList(request, data): ''' - takes { - id: listId, - user: username(only admins) - } - returns { - } + Removes a list from favorites + takes { + id: listId, + user: username(only admins) + } + returns {} + see: subscribeToList ''' list = get_list_or_404_json(data['id']) user = request.user @@ -379,14 +384,14 @@ actions.register(unsubscribeFromList, cache=False) @login_required_json def sortLists(request, data): ''' - takes { - section: 'personal', - ids: [1,2,4,3] - } - known sections: 'personal', 'public', 'featured' - featured can only be edited by admins - returns { - } + Set order of lists + takes { + section: 'personal', + ids: [1,2,4,3] + } + known sections: 'personal', 'public', 'featured' + featured can only be edited by admins + returns {} ''' position = 0 section = data['section'] diff --git a/pandora/place/views.py b/pandora/place/views.py index 88780a61..5697bd07 100644 --- a/pandora/place/views.py +++ b/pandora/place/views.py @@ -20,23 +20,24 @@ import models @login_required_json def addPlace(request, data): ''' - takes { - name: "", - alternativeNames: [], - geoname: "", - countryCode: '', - south: float, - west: float, - north: float, - east: float, - lat: float, - lng: float, - area: float, - type: "" - } - returns { - id: string - } + Adds a place + takes { + name: "", + alternativeNames: [], + geoname: "", + countryCode: '', + south: float, + west: float, + north: float, + east: float, + lat: float, + lng: float, + area: float, + type: "" + } + returns { + id: string + } ''' #FIXME: check permissions exists = False @@ -102,14 +103,15 @@ actions.register(addPlace, cache=False) @login_required_json def editPlace(request, data): ''' - takes { - id: string, - name: string - north: int - } - returns { - names: [] - } + Edits a place + takes { + id: string, + name: string + north: int + } + returns { + names: [] + } ''' place = get_object_or_404_json(models.Place, pk=ox.fromAZ(data['id'])) names = data.get('name', []) @@ -167,10 +169,12 @@ actions.register(editPlace, cache=False) @login_required_json def removePlace(request, data): ''' - takes { - id: string, - } - returns {} + Removes a place + takes { + id: string, + } + returns {} + see: addPlace, editPlace, findPlaces ''' if isinstance(data, dict): data = data['id'] @@ -215,61 +219,61 @@ def order_query(qs, sort): def findPlaces(request, data): ''' - takes { - query: { - conditions: [ - { - key: 'user', - value: 'something', - operator: '=' - } - ] - operator: "," - }, - itemsQuery: { - //see find request - }, - sort: [{key: 'name', operator: '+'}], - range: [int, int] - keys: [string] - } + takes { + query: { + conditions: [ + { + key: 'user', + value: 'something', + operator: '=' + } + ] + operator: "," + }, + itemsQuery: { + //see find request + }, + sort: [{key: 'name', operator: '+'}], + range: [int, int] + keys: [string] + } - possible query keys: - name, geoname, user + possible query keys: + name, geoname, user - itemsQuery can be used to limit the resuts to matches in those items. - Uses the same query syntax as used in the find request. + itemsQuery can be used to limit the resuts to matches in those items. + Uses the same query syntax as used in the find request. - possible keys: - name, geoname, user - - returns { - items: [object] - } - takes { - query: object, - sort: [object] - range: [int, int] - } - query: query object, more on query syntax at - https://wiki.0x2620.org/wiki/pandora/QuerySyntax - sort: array of key, operator dics - [ - { - key: "year", - operator: "-" - }, - { - key: "director", - operator: "" - } - ] - range: result range, array [from, to] + possible keys: + name, geoname, user + + returns { + items: [object] + } + takes { + query: object, + sort: [object] + range: [int, int] + } + query: query object, more on query syntax at + https://wiki.0x2620.org/wiki/pandora/QuerySyntax + sort: array of key, operator dics + [ + { + key: "year", + operator: "-" + }, + { + key: "director", + operator: "" + } + ] + range: result range, array [from, to] - with keys, items is list of dicts with requested properties: - returns { - items: [string] - } + with keys, items is list of dicts with requested properties: + returns { + items: [string] + } Positions takes { @@ -316,10 +320,11 @@ actions.register(findPlaces) def getPlaceNames(request, data): ''' - takes {} - returns { - items: [{name: string, matches: int}] - } + Undocumented + takes {} + returns { + items: [{name: string, matches: int}] + } ''' response = json_response({}) layers = [l['id'] for l in filter(lambda l: l['type'] == 'place',