update api docs

This commit is contained in:
rolux 2014-12-19 15:31:57 +00:00
parent cada20f904
commit 3950213960
11 changed files with 69 additions and 59 deletions

View file

@ -29,6 +29,11 @@ from chunk import process_chunk
@login_required_json
def removeVolume(request, data):
'''
Removes a volume
takes {} // undocumented
returns {} // undocumented
'''
user = request.user
try:
volume = models.Volume.objects.get(user=user, name=data['volume'])
@ -352,10 +357,10 @@ actions.register(taskStatus, cache=False)
@login_required_json
def moveMedia(request, data):
'''
Move media files from one item to another
Moves one or more media files from one item to another
takes {
ids: ids of files
item: new public_id
ids: [string], // list of file ids
item: id // target item id
}
returns {}
notes: This will *not* (yet) shift the corresponding annotations.

View file

@ -250,7 +250,7 @@ def sortDocuments(request, data):
Sets the sort order for the documents related to a given item
takes {
item: string, // item id
ids: [string] // list of document ids
ids: [string] // ordered list of document ids
}
returns {}
see: addDocument, editDocument, findDocument, removeDocument, sortDocuments

View file

@ -141,13 +141,12 @@ actions.register(editClip, cache=False)
@login_required_json
def orderClips(request, data):
'''
Updates manual ordering of clips within an edit
Sets the manual ordering of clips within a given edit
takes {
edit: string, // edit id
ids: [string] // clip ids in new order
}
returns {
}
returns {}
see: addClips, editClip, removeClip, sortClips
'''
edit = get_edit_or_404_json(data['edit'])
@ -207,7 +206,7 @@ def sortClips(request, data):
sort: object // sort
}
returns {}
note: sort is [{key: string, operator: string}], operator can be '+' or '-'
notes: sort is [{key: string, operator: string}], operator can be '+' or '-'
see: addClips, editClip, orderClips, removeClips
'''
edit = get_edit_or_404_json(data['edit'])
@ -486,7 +485,8 @@ def sortEdits(request, data):
ids: [string] // ordered list of edit ids
}
returns {}
notes: Sorting featured edits requires a specific per-user capability
notes: Setting the order of featured edits requires the appropriate
capability.
see: addEdit, editEdits, findEdits, getEdit, removeEdit
'''
position = 0

View file

@ -240,11 +240,12 @@ def getEntity(request, data):
'''
Gets an entity by id
takes {
id: string,
keys: [string]
id: string, // entity id
keys: [string] // list of properties to return
}
returns {
key: value
key: value, // property id and value
... // more key/value pairs
}
see: addEntity, editEntity, findEntities, removeEntity
'''
@ -258,14 +259,12 @@ actions.register(getEntity)
@login_required_json
def removeEntity(request, data):
'''
Removes an entity
Removes one or more entities
takes {
id: string,
or
ids: [string]
}
returns {
id: string, // either entity id
ids: [string] // or list of entity ids
}
returns {}
see: addEntity, editEntity, findEntities, getEntity
'''
response = json_response()

View file

@ -582,7 +582,7 @@ def remove(request, data):
id: string // item id
}
returns {}
notes: The return status is 200 for success or 403 for permission denied.
notes: The return status code is 200 for success or 403 for permission denied.
see: add, edit, find, get, lookup, upload
'''
response = json_response({})

View file

@ -110,12 +110,12 @@ def getList(request, data):
'''
Gets a list by id
takes {
id: listid
id: string // list id
}
returns {
id:
section:
...
id: string, // list id
section: string, // lists section (like 'personal')
... // more key/value pairs
}
see: addList, editList, findLists, removeList, sortLists
'''
@ -374,7 +374,7 @@ actions.register(unsubscribeFromList, cache=False)
@login_required_json
def sortLists(request, data):
'''
Set order of lists
Sets the order of lists in a given section
takes {
section: string, // lists section
ids: [string] // ordered list of lists
@ -382,6 +382,7 @@ def sortLists(request, data):
returns {}
notes: Possible sections are 'personal', 'favorite' and 'featured'. Setting
the order of featured lists requires the appropriate capability.
see: addList, editList, findLists, getList, removeList
'''
position = 0
section = data['section']

View file

@ -54,7 +54,7 @@ def sortName(request, data):
name: sortName, // sort name for this name
... // more results
}
see editName, findNames
see: editName, findNames
'''
names = data.get('names', [])
if 'name' in data:

View file

@ -51,16 +51,17 @@ def order_query(qs, sort):
def findSequences(request, data):
'''
takes {
query: ...
itemsQuery: ...
}
one of your conditions has to be key: 'mode', value: [shape,color], operator: '=='
returns {
items: [object]
}
Finds sequences for a given query
takes {
query: object // query object, see `find`
itemsQuery: object // limit to matching items, query object, see `find`
}
returns {
items: [object] // list of sequences
}
notes: One of the query conditions has to be {key: 'mode', operator: '==',
value: 'color' or 'shape'}.
see: find, getSequence
'''
response = json_response()
@ -93,18 +94,19 @@ actions.register(findSequences)
def getSequence(request, data):
'''
takes {
id
mode
position
}
returns {
id
mode
in
out
}
Gets a sequence by id
takes {
id: string, // sequence id
mode: string, // sequence mode ('color' or 'shape')
position: int // position in seconds
}
returns {
id: string, // sequence id
mode: string, // sequence mode ('color' or 'shape')
in: int, // in point in seconds
out: int // out point in seconds
}
see: findSequences
'''
response = json_response()
position = float('%0.03f' % data['position'])

View file

@ -202,7 +202,7 @@ def findTexts(request, data):
}
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
see: addText, editText, find, getText, removeText, sortTexts
'''
query = parse_query(data, request.user)
@ -317,7 +317,8 @@ def sortTexts(request, data):
ids: [string] // ordered list of text ids
}
returns {}
notes: Sorting featured texts requires the appropriate capability.
notes: Setting the order of featured texts requires the appropriate
capability.
see: addText, findTexts, getText, editText, removeText
'''
position = 0

View file

@ -11,15 +11,16 @@ from ox.django.api import actions
def tv(request, data):
'''
takes {
list: string
}
returns {
item: string,
position: float,
title: string,
...
}
Gets TV program for a given list
takes {
list: string // list name
}
returns {
item: string, // current item
position: float, // current position in seconds
title: string, // item title
... // more item properties
}
'''
if 'list' in data and data['list']:
list = get_list_or_404_json(data['list'])

View file

@ -495,7 +495,7 @@ def findUsers(request, data):
}
notes: Possible query keys are 'browser', 'email', 'groups', 'lastLogin'
and 'username'.
see: editUser, findUser, getUser, removeUser
see: editUser, find, findUser, getUser, removeUser
'''
response = json_response(status=200, text='ok')
query = parse_query(data, request.user)
@ -550,6 +550,7 @@ actions.register(getUser)
@login_required_json
def mail(request, data):
'''
Sends mail to a list of users
takes {
to: [string], // list of usernames of recipients
subject: string, // subject