From bd2d9f2e57307339772641618188c4603946dfa1 Mon Sep 17 00:00:00 2001 From: rolux Date: Thu, 18 Dec 2014 20:56:28 +0000 Subject: [PATCH] update api docs --- pandora/entity/views.py | 9 +-- pandora/event/views.py | 2 +- pandora/item/views.py | 9 +-- pandora/text/views.py | 148 ++++++++++++++++++++-------------------- pandora/user/views.py | 58 +++++++++------- 5 files changed, 116 insertions(+), 110 deletions(-) diff --git a/pandora/entity/views.py b/pandora/entity/views.py index d34000083..44369f035 100644 --- a/pandora/entity/views.py +++ b/pandora/entity/views.py @@ -88,14 +88,15 @@ actions.register(addEntity, cache=False) def autocompleteEntities(request, data): ''' + Returns entities for a given entity type and search string takes { - key: string, - value: string, + key: string, // entity type + value: string, // search string operator: string // '=', '==', '^', '$' - range: [int, int] + range: [int, int] // range of results to return } returns { - items: [{id, name,...}, ...] // array of matching entities + items: [{id, name, ...}, ...] // list of matching entities } see: autocomplete ''' diff --git a/pandora/event/views.py b/pandora/event/views.py index ba006bce1..86bcf5779 100644 --- a/pandora/event/views.py +++ b/pandora/event/views.py @@ -130,7 +130,7 @@ def removeEvent(request, data): ''' Removes a calendar event takes { - id: event id + id: string // event id } returns {} see: addEvent, editEvent, findEvents diff --git a/pandora/item/views.py b/pandora/item/views.py index ed644373c..95b6cea46 100644 --- a/pandora/item/views.py +++ b/pandora/item/views.py @@ -289,15 +289,16 @@ actions.register(find) def autocomplete(request, data): ''' + Returns autocomplete strings for a given item key and search string takes { - key: string, - value: string, + key: string, // item key + value: string, // search string operator: string, // '=', '==', '^', '$' query: object, // item query to limit results, see `find` - range: [int, int] + range: [int, int] // range of tesults to return } returns { - items: [string, ...] // array of matching values + items: [string, ...] // list of matching strings } see: autocompleteEntities ''' diff --git a/pandora/text/views.py b/pandora/text/views.py index 04368c369..3d7be7272 100644 --- a/pandora/text/views.py +++ b/pandora/text/views.py @@ -30,14 +30,16 @@ def get_text_or_404_json(id): @login_required_json def addText(request, data): ''' - takes { - name: value, - } - returns { - id: - name: - ... - } + Adds a new text + takes { + name: string // text name + } + returns { + id: string, // text id + name: string // text name + ... more key/value pairs + } + see: editText, findTexts, getText, removeText, sortTexts ''' data['name'] = re.sub(' \[\d+\]$', '', data.get('name', 'Untitled')).strip() name = data['name'] @@ -74,15 +76,17 @@ actions.register(addText, cache=False) def getText(request, data): ''' - takes { - id: textid, - keys: [] - } - returns { - id: - text: - ... - } + Gets a text by id + takes { + id: string, // text id + keys: [string] // list of properties to return + } + returns { + id: string, // text id + key: value, // property and value + ... // more key/value pairs + } + see: addText, findTexts, editText, removeText, sortTexts ''' response = json_response() public_id = data['id'] @@ -113,16 +117,17 @@ actions.register(getText) @login_required_json def editText(request, data): ''' - takes { - id: - text: - public: boolean - } - returns { - id: - text: - ... - } + Edits a text + takes { + id: string, // text id + text: string, // text + public: boolean // if true, text is publix + } + returns { + id: string, // text id + ... // more key/value pairs + } + see: addText, findTexts, getText, removeText, sortTexts ''' response = json_response() if data['id']: @@ -185,32 +190,19 @@ def parse_query(data, user): def findTexts(request, data): ''' - takes { - query: { - conditions: [ - { - key: 'user', - value: 'something', - operator: '=' - } - ] - operator: "," - }, - sort: [{key: 'name', operator: '+'}], - range: [0, 100] - keys: [] - } - - possible query keys: - name, user, featured, subscribed - - possible keys: - name, user, featured, subscribed, query - - } - returns { - items: [object] - } + Finds texts for a given query + takes { + keys: [], // list of keys to return, see `find` + query: object, // query object, see `find` + range: [int, int], // range of items to return + sort: [object], list of sort objects, see `find` + } + returns { + items: [object] // list of text objects + } + notes: Possible query keys are 'featured', 'name', 'subscribed' and 'user', + possible keys are 'featured', 'name', 'query', 'subscribed' and 'user'. + see: addText, editText, getText, removeText, sortTexts ''' query = parse_query(data, request.user) @@ -250,11 +242,12 @@ actions.register(findTexts) @login_required_json def removeText(request, data): ''' - takes { - id: string, - } - returns { - } + Removes a text + takes { + id: string // text id + } + returns {} + see: addText, editText, findTexts, getText, sortTexts ''' text = get_text_or_404_json(data['id']) response = json_response() @@ -270,10 +263,13 @@ actions.register(removeText, cache=False) @login_required_json def subscribeToText(request, data): ''' - takes { - id: string, - } - returns {} + Adds a text to favorites + takes { + id: string, // text id + user: string // username (admin-only) + } + returns {} + see: unsubscribeFromText ''' text = get_text_or_404_json(data['id']) user = request.user @@ -294,11 +290,13 @@ actions.register(subscribeToText, cache=False) @login_required_json def unsubscribeFromText(request, data): ''' - takes { - id: string, - user: username(only admins) - } - returns {} + Removes a text from favorites + takes { + id: string // text id + user: string // username (admin-only) + } + returns {} + see: subscribeToText ''' text = get_text_or_404_json(data['id']) user = request.user @@ -313,14 +311,14 @@ actions.register(unsubscribeFromText, cache=False) @login_required_json def sortTexts(request, data): ''' - takes { - section: 'personal', - ids: [1,2,4,3] - } - known sections: 'personal', 'public', 'featured' - featured can only be edited by admins - - returns {} + Sets manual ordering of texts in a given folder + takes { + section: string, // 'personal', 'favorite' or 'featured' + ids: [string] // ordered list of text ids + } + returns {} + notes: Sorting featured texts requires the appropriate capability. + see: addText, findTexts, getText, editText, removeText ''' position = 0 section = data['section'] diff --git a/pandora/user/views.py b/pandora/user/views.py index c70faa3cf..620e32892 100644 --- a/pandora/user/views.py +++ b/pandora/user/views.py @@ -223,18 +223,17 @@ def resetPassword(request, data): ''' Resets password for a given user takes { - username: string, - password: string, - code: string + username: string, // username + password: string, // password + code: string // token } returns { errors: { - code: 'Incorrect Code' - } - user { - } + code: 'Incorrect Code' // on error + }, + user: object // on success } - see: ... + see: resetPassword ''' if 'code' in data and 'password' in data: if not data['password']: @@ -276,16 +275,17 @@ def requestToken(request, data): ''' Requests a password reset token takes { - username: string, - email: string + username: string, // either username + email: string // or e-mail address } returns { errors: { - username: 'Unknown Username' - email: 'Unknown Email' + username: 'Unknown Username', // on error + email: 'Unknown Email' // on error } - username: user + username: string // on success } + see: requestToken ''' user = None if 'username' in data: @@ -341,12 +341,13 @@ def editUser(request, data): ''' Edits a user takes { - key: value - } - required key: id - optional keys: username, email, level, notes - returns { + id: string, // user id + key: value, // property id and new value + ... // more key/value pairs } + returns {} + notes: Possible keys are 'email', 'id', 'level', 'notes', 'username' + see: removeUser ''' response = json_response() user = get_object_or_404_json(User, pk=ox.fromAZ(data['id'])) @@ -395,10 +396,14 @@ actions.register(editUser, cache=False) @capability_required_json('canManageUsers') def removeUser(request, data): ''' + Removes a user takes { - username: username + username: string // username } returns {} + notes: Note that this will only disable the user account -- annotations + will not be removed. + see: editUser, findUser ''' response = json_response() u = get_user_or_404(data) @@ -410,17 +415,18 @@ actions.register(removeUser, cache=False) def findUser(request, data): ''' + Finds users for a given query takes { - key: string, //username, email - value: string, - operator: "==" // "==", "=" - keys: [string] + key: string, // username, email + value: string, // search string + operator: "==" // "==" or "=" + keys: [string] // list of properties to return } - returns { - users: [object] + users: [object] // list of users } - see: editUser + notes: Possible keys ... undocumented + see: editUser, removeUser ''' response = json_response(status=200, text='ok') #keys = data.get('keys')