update api docs

This commit is contained in:
rolux 2014-12-19 13:20:53 +00:00
parent 4a084d8405
commit 5ac0c04d37

View file

@ -48,17 +48,15 @@ def signin(request, data):
''' '''
Sign in Sign in
takes { takes {
username: string, username: string, // username
password: string password: string // password
} }
returns { returns {
errors: { errors: {
username: 'Unknown Username', username: 'Unknown Username', // in case of error
password: 'Incorrect Password' password: 'Incorrect Password' // in case of error
}
user: {
...
} }
user: object // user data, in case of success
} }
see: signout, signup see: signout, signup
''' '''
@ -112,10 +110,7 @@ def signout(request, data):
Sign out Sign out
takes {} takes {}
returns { returns {
user: { // default user user: object // default user data
key: value, // user data
... // more user daa
}
} }
see: signin, signup see: signin, signup
''' '''
@ -137,19 +132,16 @@ def signup(request, data):
''' '''
Sign up Sign up
takes { takes {
username: string, username: string, // username
password: string, password: string, // password
email: string email: string // e-mail address
} }
returns { returns {
errors: { errors: {
username: 'Unknown Username', username: 'Username already exists', // in case of error
password: 'Incorrect Password' password: 'E-mail address already exists' // in case of error
}
user: {
...
} }
user: object // user data, in case of success
} }
see: signin, signout see: signin, signout
''' '''
@ -166,7 +158,7 @@ def signup(request, data):
elif User.objects.filter(email__iexact=data['email']).count() > 0: elif User.objects.filter(email__iexact=data['email']).count() > 0:
response = json_response({ response = json_response({
'errors': { 'errors': {
'email': 'Email address already exists' 'email': 'E-mail address already exists'
} }
}) })
elif not data['password']: elif not data['password']:
@ -233,7 +225,7 @@ def resetPassword(request, data):
}, },
user: object // on success user: object // on success
} }
see: resetPassword see: requestToken
''' '''
if 'code' in data and 'password' in data: if 'code' in data and 'password' in data:
if not data['password']: if not data['password']:
@ -285,7 +277,7 @@ def requestToken(request, data):
} }
username: string // on success username: string // on success
} }
see: requestToken see: resetPassword
''' '''
user = None user = None
if 'username' in data: if 'username' in data:
@ -347,7 +339,7 @@ def editUser(request, data):
} }
returns {} returns {}
notes: Possible keys are 'email', 'id', 'level', 'notes', 'username' notes: Possible keys are 'email', 'id', 'level', 'notes', 'username'
see: removeUser see: findUser, findUsers, getUser, removeUser
''' '''
response = json_response() response = json_response()
user = get_object_or_404_json(User, pk=ox.fromAZ(data['id'])) user = get_object_or_404_json(User, pk=ox.fromAZ(data['id']))
@ -403,7 +395,7 @@ def removeUser(request, data):
returns {} returns {}
notes: Note that this will only disable the user account -- annotations notes: Note that this will only disable the user account -- annotations
will not be removed. will not be removed.
see: editUser, findUser see: editUser, findUser, findUsers, getUser
''' '''
response = json_response() response = json_response()
u = get_user_or_404(data) u = get_user_or_404(data)
@ -415,18 +407,17 @@ actions.register(removeUser, cache=False)
def findUser(request, data): def findUser(request, data):
''' '''
Finds users for a given query Finds users by username or e-mail address
takes { takes {
key: string, // username, email key: string, // 'username' or 'email'
value: string, // search string value: string, // search string
operator: "==" // "==" or "=" operator: string // '=' (partial match) or '==' (exact match)
keys: [string] // list of properties to return keys: [string] // list of properties to return
} }
returns { returns {
users: [object] // list of users users: [object] // list of users
} }
notes: Possible keys ... undocumented see: editUser, findUsers, getUser, removeUser
see: editUser, removeUser
''' '''
response = json_response(status=200, text='ok') response = json_response(status=200, text='ok')
#keys = data.get('keys') #keys = data.get('keys')
@ -492,67 +483,19 @@ def order_query(qs, sort):
@capability_required_json('canManageUsers') @capability_required_json('canManageUsers')
def findUsers(request, data): def findUsers(request, data):
''' '''
Finds users for a given query
takes { takes {
query: { query: object, // query object, see `find`
conditions: [ sort: [object], // list of sort objects, see `find`
{ range: [int, int], // range of results to return
key: 'user', keys: [string] // list of properties to return
value: 'something',
operator: '='
} }
]
operator: ","
},
sort: [{key: 'username', operator: '+'}],
range: [0, 100]
keys: []
}
possible query keys:
username, email, lastLogin, browser, groups
returns { returns {
items: [ items: [object] // list of user objects
{name:, user:, featured:, public...}
]
} }
notes: Possible query keys are 'browser', 'email', 'groups', 'lastLogin'
takes { and 'username'.
query: query, see: editUser, findUser, getUser, removeUser
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
[
{
key: "year",
operator: "-"
},
{
key: "director",
operator: ""
}
]
range: result range, array [from, to]
with keys, items is list of dicts with requested properties:
returns {
items: [object]
}
Positions
takes {
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
see: editUser
''' '''
response = json_response(status=200, text='ok') response = json_response(status=200, text='ok')
query = parse_query(data, request.user) query = parse_query(data, request.user)
@ -586,14 +529,17 @@ actions.register(findUsers)
@capability_required_json('canManageUsers') @capability_required_json('canManageUsers')
def getUser(request, data): def getUser(request, data):
''' '''
Gets a user by id or username
takes { takes {
id: string or username: string, id: string, // either user id
keys: [] username: string, // or username
keys: [string] // list of properties to return
} }
returns { returns {
id: string, id: string, // user id
... ... // more key/value pairs
} }
see: editUser, findUser, findUsers, removeUser
''' '''
response = json_response() response = json_response()
u = get_user_or_404(data) u = get_user_or_404(data)
@ -605,17 +551,14 @@ actions.register(getUser)
def mail(request, data): def mail(request, data):
''' '''
takes { takes {
to: [string], // array of usernames to send mail to to: [string], // list of usernames of recipients
subject: string, subject: string, // subject
message: string message: string // message
}
message can contain {username} or {email},
this will be replace with the user/email
the mail is sent to.
returns {
} }
returns {}
notes: The message can contain '{username}' or '{email}', which will be
replaced with the individual value.
see: contact
''' '''
response = json_response() response = json_response()
p = request.user.get_profile() p = request.user.get_profile()
@ -741,9 +684,10 @@ def editPreferences(request, data):
''' '''
Edits the preferences of the current user Edits the preferences of the current user
takes { takes {
key: value key: value, // property id and new value
... // more properties
} }
keys: email, password notes: Possible keys are 'email' and 'password'.
returns {} returns {}
''' '''
errors = {} errors = {}