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): def autocompleteEntities(request, data):
''' '''
Returns entities for a given entity type and search string
takes { takes {
key: string, key: string, // entity type
value: string, value: string, // search string
operator: string // '=', '==', '^', '$' operator: string // '=', '==', '^', '$'
range: [int, int] range: [int, int] // range of results to return
} }
returns { returns {
items: [{id, name,...}, ...] // array of matching entities items: [{id, name, ...}, ...] // list of matching entities
} }
see: autocomplete see: autocomplete
''' '''

View file

@ -130,7 +130,7 @@ def removeEvent(request, data):
''' '''
Removes a calendar event Removes a calendar event
takes { takes {
id: event id id: string // event id
} }
returns {} returns {}
see: addEvent, editEvent, findEvents see: addEvent, editEvent, findEvents

View file

@ -289,15 +289,16 @@ actions.register(find)
def autocomplete(request, data): def autocomplete(request, data):
''' '''
Returns autocomplete strings for a given item key and search string
takes { takes {
key: string, key: string, // item key
value: string, value: string, // search string
operator: string, // '=', '==', '^', '$' operator: string, // '=', '==', '^', '$'
query: object, // item query to limit results, see `find` query: object, // item query to limit results, see `find`
range: [int, int] range: [int, int] // range of tesults to return
} }
returns { returns {
items: [string, ...] // array of matching values items: [string, ...] // list of matching strings
} }
see: autocompleteEntities see: autocompleteEntities
''' '''

View file

@ -30,14 +30,16 @@ def get_text_or_404_json(id):
@login_required_json @login_required_json
def addText(request, data): def addText(request, data):
''' '''
Adds a new text
takes { takes {
name: value, name: string // text name
} }
returns { returns {
id: id: string, // text id
name: name: string // text name
... ... more key/value pairs
} }
see: editText, findTexts, getText, removeText, sortTexts
''' '''
data['name'] = re.sub(' \[\d+\]$', '', data.get('name', 'Untitled')).strip() data['name'] = re.sub(' \[\d+\]$', '', data.get('name', 'Untitled')).strip()
name = data['name'] name = data['name']
@ -74,15 +76,17 @@ actions.register(addText, cache=False)
def getText(request, data): def getText(request, data):
''' '''
Gets a text by id
takes { takes {
id: textid, id: string, // text id
keys: [] keys: [string] // list of properties to return
} }
returns { returns {
id: id: string, // text id
text: key: value, // property and value
... ... // more key/value pairs
} }
see: addText, findTexts, editText, removeText, sortTexts
''' '''
response = json_response() response = json_response()
public_id = data['id'] public_id = data['id']
@ -113,16 +117,17 @@ actions.register(getText)
@login_required_json @login_required_json
def editText(request, data): def editText(request, data):
''' '''
Edits a text
takes { takes {
id: id: string, // text id
text: text: string, // text
public: boolean public: boolean // if true, text is publix
} }
returns { returns {
id: id: string, // text id
text: ... // more key/value pairs
...
} }
see: addText, findTexts, getText, removeText, sortTexts
''' '''
response = json_response() response = json_response()
if data['id']: if data['id']:
@ -185,32 +190,19 @@ def parse_query(data, user):
def findTexts(request, data): def findTexts(request, data):
''' '''
Finds texts for a given query
takes { takes {
query: { keys: [], // list of keys to return, see `find`
conditions: [ query: object, // query object, see `find`
{ range: [int, int], // range of items to return
key: 'user', sort: [object], list of sort objects, see `find`
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 { returns {
items: [object] 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) query = parse_query(data, request.user)
@ -250,11 +242,12 @@ actions.register(findTexts)
@login_required_json @login_required_json
def removeText(request, data): def removeText(request, data):
''' '''
Removes a text
takes { takes {
id: string, id: string // text id
}
returns {
} }
returns {}
see: addText, editText, findTexts, getText, sortTexts
''' '''
text = get_text_or_404_json(data['id']) text = get_text_or_404_json(data['id'])
response = json_response() response = json_response()
@ -270,10 +263,13 @@ actions.register(removeText, cache=False)
@login_required_json @login_required_json
def subscribeToText(request, data): def subscribeToText(request, data):
''' '''
Adds a text to favorites
takes { takes {
id: string, id: string, // text id
user: string // username (admin-only)
} }
returns {} returns {}
see: unsubscribeFromText
''' '''
text = get_text_or_404_json(data['id']) text = get_text_or_404_json(data['id'])
user = request.user user = request.user
@ -294,11 +290,13 @@ actions.register(subscribeToText, cache=False)
@login_required_json @login_required_json
def unsubscribeFromText(request, data): def unsubscribeFromText(request, data):
''' '''
Removes a text from favorites
takes { takes {
id: string, id: string // text id
user: username(only admins) user: string // username (admin-only)
} }
returns {} returns {}
see: subscribeToText
''' '''
text = get_text_or_404_json(data['id']) text = get_text_or_404_json(data['id'])
user = request.user user = request.user
@ -313,14 +311,14 @@ actions.register(unsubscribeFromText, cache=False)
@login_required_json @login_required_json
def sortTexts(request, data): def sortTexts(request, data):
''' '''
Sets manual ordering of texts in a given folder
takes { takes {
section: 'personal', section: string, // 'personal', 'favorite' or 'featured'
ids: [1,2,4,3] ids: [string] // ordered list of text ids
} }
known sections: 'personal', 'public', 'featured'
featured can only be edited by admins
returns {} returns {}
notes: Sorting featured texts requires the appropriate capability.
see: addText, findTexts, getText, editText, removeText
''' '''
position = 0 position = 0
section = data['section'] section = data['section']

View file

@ -223,18 +223,17 @@ def resetPassword(request, data):
''' '''
Resets password for a given user Resets password for a given user
takes { takes {
username: string, username: string, // username
password: string, password: string, // password
code: string code: string // token
} }
returns { returns {
errors: { errors: {
code: 'Incorrect Code' code: 'Incorrect Code' // on error
},
user: object // on success
} }
user { see: resetPassword
}
}
see: ...
''' '''
if 'code' in data and 'password' in data: if 'code' in data and 'password' in data:
if not data['password']: if not data['password']:
@ -276,16 +275,17 @@ def requestToken(request, data):
''' '''
Requests a password reset token Requests a password reset token
takes { takes {
username: string, username: string, // either username
email: string email: string // or e-mail address
} }
returns { returns {
errors: { errors: {
username: 'Unknown Username' username: 'Unknown Username', // on error
email: 'Unknown Email' email: 'Unknown Email' // on error
} }
username: user username: string // on success
} }
see: requestToken
''' '''
user = None user = None
if 'username' in data: if 'username' in data:
@ -341,12 +341,13 @@ def editUser(request, data):
''' '''
Edits a user Edits a user
takes { takes {
key: value id: string, // user id
} key: value, // property id and new value
required key: id ... // more key/value pairs
optional keys: username, email, level, notes
returns {
} }
returns {}
notes: Possible keys are 'email', 'id', 'level', 'notes', 'username'
see: 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']))
@ -395,10 +396,14 @@ actions.register(editUser, cache=False)
@capability_required_json('canManageUsers') @capability_required_json('canManageUsers')
def removeUser(request, data): def removeUser(request, data):
''' '''
Removes a user
takes { takes {
username: username username: string // username
} }
returns {} returns {}
notes: Note that this will only disable the user account -- annotations
will not be removed.
see: editUser, findUser
''' '''
response = json_response() response = json_response()
u = get_user_or_404(data) u = get_user_or_404(data)
@ -410,17 +415,18 @@ actions.register(removeUser, cache=False)
def findUser(request, data): def findUser(request, data):
''' '''
Finds users for a given query
takes { takes {
key: string, //username, email key: string, // username, email
value: string, value: string, // search string
operator: "==" // "==", "=" operator: "==" // "==" or "="
keys: [string] keys: [string] // list of properties to return
} }
returns { returns {
users: [object] users: [object] // list of users
} }
see: editUser notes: Possible keys ... undocumented
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')