update api docs

This commit is contained in:
rolux 2014-12-18 18:43:35 +00:00
parent 3024c0225b
commit ec508dd6b7

View file

@ -46,11 +46,11 @@ def get_group_or_404(data):
def signin(request, data):
'''
Sign in
takes {
username: string,
password: string
}
returns {
errors: {
username: 'Unknown Username',
@ -60,6 +60,7 @@ def signin(request, data):
...
}
}
see: signout, signup
'''
if 'assertion' in data:
response = persona.signin(request)
@ -108,13 +109,15 @@ actions.register(signin, cache=False)
def signout(request, data):
'''
Sign out
takes {}
returns {
user: {
default user
user: { // default user
key: value, // user data
... // more user daa
}
}
see: signin, signup
'''
response = json_response(text='ok')
if request.user.is_authenticated():
@ -132,6 +135,7 @@ actions.register(signout, cache=False)
def signup(request, data):
'''
Sign up
takes {
username: string,
password: string,
@ -147,6 +151,7 @@ def signup(request, data):
...
}
}
see: signin, signout
'''
if 'username' in data and 'password' in data:
data['username'] = data['username'].strip()
@ -216,12 +221,12 @@ actions.register(signup, cache=False)
def resetPassword(request, data):
'''
Resets password for a given user
takes {
username: string,
password: string,
code: string
}
returns {
errors: {
code: 'Incorrect Code'
@ -229,6 +234,7 @@ def resetPassword(request, data):
user {
}
}
see: ...
'''
if 'code' in data and 'password' in data:
if not data['password']:
@ -268,11 +274,11 @@ actions.register(resetPassword, cache=False)
def requestToken(request, data):
'''
Requests a password reset token
takes {
username: string,
email: string
}
returns {
errors: {
username: 'Unknown Username'
@ -333,12 +339,12 @@ actions.register(requestToken, cache=False)
@capability_required_json('canManageUsers')
def editUser(request, data):
'''
Edits a user
takes {
key: value
}
required key: id
optional keys: username, email, level, notes
returns {
}
'''
@ -414,6 +420,7 @@ def findUser(request, data):
returns {
users: [object]
}
see: editUser
'''
response = json_response(status=200, text='ok')
#keys = data.get('keys')
@ -539,6 +546,7 @@ 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
see: editUser
'''
response = json_response(status=200, text='ok')
query = parse_query(data, request.user)
@ -653,12 +661,12 @@ actions.register(mail, cache=False)
def contact(request, data):
'''
Sends a message to the contact address
takes {
email: string,
subject: string,
message: string
}
returns {
}
'''
@ -725,6 +733,7 @@ def getPositionById(list, key):
@login_required_json
def editPreferences(request, data):
'''
Edits the current user's preferences
takes {
key: value
}
@ -768,12 +777,10 @@ def reset_ui(request):
def resetUI(request, data):
'''
reset user ui settings to defaults
takes {
}
returns {
}
Resets the user's UI settings to the default state
takes {}
returns {}
see: setUI
'''
response = json_response()
if request.user.is_authenticated():
@ -788,14 +795,14 @@ actions.register(resetUI, cache=False)
def setUI(request, data):
'''
Sets one or more UI settings for the current user
takes {
key.subkey: value
}
you can set nested keys
api.setUI({"lists|my|ListView": "icons"})
returns {
key: value, // property and new value
... // more key/value pairs
}
returns {}
notes: To set nested keys, use {'foo.bar.baz': value}
see: resetUI
'''
if request.user.is_authenticated():
profile = request.user.get_profile()
@ -840,9 +847,10 @@ actions.register(setUI, cache=False)
@capability_required_json('canManageUsers')
def statistics(request, data):
'''
Gets usage statistics
takes {}
returns {
...
... // undocumented
}
'''
response = json_response()
@ -869,13 +877,14 @@ def group_json(g):
@login_required_json
def getGroups(request, data):
'''
Gets user groups
takes {}
returns {
groups: [
{id: string, name: string, users: int, items: int}
]
}
see: addGroup, editGroup, getGroups, removeGroup
'''
response = json_response(status=200, text='ok')
response['data']['groups'] = []
@ -888,6 +897,7 @@ actions.register(getGroups)
@login_required_json
def getGroup(request, data):
'''
Gets user group
takes {
id: string
or
@ -899,7 +909,7 @@ def getGroup(request, data):
users: int
items: int
}
see: addGroup, editGroup, getGroups, removeGroup
'''
response = json_response(status=200, text='ok')
g = get_group_or_404(data)
@ -911,6 +921,7 @@ actions.register(getGroup, cache=False)
@capability_required_json('canManageUsers')
def addGroup(request, data):
'''
Adds user group
takes {
name: string
}
@ -920,7 +931,7 @@ def addGroup(request, data):
users: int
items: int
}
see: editGroup, getGroup, getGroups, removeGroup
'''
response = json_response(status=200, text='ok')
created = False
@ -940,6 +951,7 @@ actions.register(addGroup, cache=False)
@capability_required_json('canManageUsers')
def editGroup(request, data):
'''
Edits user group
takes {
id: string,
name: string
@ -949,7 +961,7 @@ def editGroup(request, data):
name: string
users: int
}
see: addGroup, getGroup, getGroups, removeGroup
'''
response = json_response(status=200, text='ok')
g = Group.objects.get(id=ox.fromAZ(data['id']))
@ -964,12 +976,13 @@ actions.register(editGroup, cache=False)
@capability_required_json('canManageUsers')
def removeGroup(request, data):
'''
Removes user group
takes {
id: string
}
returns {
}
see: addGroup, editGroup, getGroup, getGroups
'''
response = json_response(status=200, text='ok')
g = get_group_or_404(data)