update api docs

This commit is contained in:
rolux 2014-12-18 20:56:28 +00:00
parent 6bd001a10a
commit bd2d9f2e57
5 changed files with 116 additions and 110 deletions

View file

@ -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
'''

View file

@ -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

View file

@ -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
'''

View file

@ -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']

View file

@ -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')