update api docs
This commit is contained in:
rolux
parent
9c28041171
commit
7cfdf7b8db
3 changed files with 192 additions and 178 deletions
|
|
@ -29,16 +29,13 @@ def get_document_or_404_json(id):
|
|||
@login_required_json
|
||||
def addDocument(request, data):
|
||||
'''
|
||||
add document(s) to item
|
||||
takes {
|
||||
item: string or [string]
|
||||
|
||||
id: string
|
||||
or
|
||||
ids: [string]
|
||||
}
|
||||
returns {
|
||||
}
|
||||
Adds one or more documents to one or more items
|
||||
takes {
|
||||
item: string or [string], // one or more item ids
|
||||
id: string or [string] // one or more document ids
|
||||
}
|
||||
returns {}
|
||||
see: editDocument, findDocument, getDocument, removeDocument, sortDocuments
|
||||
'''
|
||||
response = json_response()
|
||||
if 'ids' in data:
|
||||
|
|
@ -68,16 +65,20 @@ actions.register(addDocument, cache=False)
|
|||
@login_required_json
|
||||
def editDocument(request, data):
|
||||
'''
|
||||
takes {
|
||||
id: string
|
||||
name: string
|
||||
description: string
|
||||
item(optional): edit descriptoin per item
|
||||
}
|
||||
returns {
|
||||
id:
|
||||
...
|
||||
}
|
||||
takes {
|
||||
id: string, // document id
|
||||
name: string, // new document name
|
||||
description: string // new document description
|
||||
item: string // item id (optional)
|
||||
}
|
||||
returns {
|
||||
id:
|
||||
...
|
||||
}
|
||||
notes: If `item` is present, this will not edit the global description of
|
||||
the document, but its specific description in the context of the given
|
||||
item.
|
||||
see: addDocument, findDocument, getDocument, removeDocument, sortDocuments
|
||||
'''
|
||||
response = json_response()
|
||||
item = 'item' in data and Item.objects.get(public_id=data['item']) or None
|
||||
|
|
@ -140,32 +141,22 @@ def parse_query(data, user):
|
|||
|
||||
def findDocuments(request, data):
|
||||
'''
|
||||
takes {
|
||||
query: {
|
||||
conditions: [
|
||||
{
|
||||
key: 'user',
|
||||
value: 'something',
|
||||
operator: '='
|
||||
}
|
||||
]
|
||||
operator: ","
|
||||
},
|
||||
sort: [{key: 'name', operator: '+'}],
|
||||
range: [0, 100]
|
||||
keys: []
|
||||
}
|
||||
|
||||
possible query keys:
|
||||
name, user, extension, size
|
||||
|
||||
possible keys:
|
||||
name, user, extension, size
|
||||
|
||||
}
|
||||
returns {
|
||||
items: [object]
|
||||
}
|
||||
takes {
|
||||
query: object, // query object, see `find`
|
||||
sort: [object], // list of sort objects, see `find`
|
||||
range: [int, int], // range of results, per current sort order
|
||||
keys: [string] // list of keys to return
|
||||
}
|
||||
returns {
|
||||
items: [{ // list of documents
|
||||
key: value, // item key and value
|
||||
... // more key/value pairs
|
||||
}]
|
||||
}
|
||||
Notes: Query keys and keys to be returned can be 'extension', 'name',
|
||||
'size' and 'user'.
|
||||
see: addDocument, editDocument, find, getDocument, removeDocument,
|
||||
sortDocuments
|
||||
'''
|
||||
query = parse_query(data, request.user)
|
||||
|
||||
|
|
@ -193,13 +184,16 @@ actions.register(findDocuments)
|
|||
|
||||
def getDocument(request, data):
|
||||
'''
|
||||
takes {
|
||||
id: string,
|
||||
keys: [string]
|
||||
}
|
||||
returns {
|
||||
key: value
|
||||
}
|
||||
Gets a document by id
|
||||
takes {
|
||||
id: string, // document id
|
||||
keys: [string] // list of properties to return
|
||||
}
|
||||
returns {
|
||||
key: value, // document key and value
|
||||
... // more key/value pairs
|
||||
}
|
||||
see: addDocument, editDocument, findDocument, removeDocument, sortDocuments
|
||||
'''
|
||||
response = json_response({})
|
||||
data['keys'] = data.get('keys', [])
|
||||
|
|
@ -211,17 +205,15 @@ actions.register(getDocument)
|
|||
@login_required_json
|
||||
def removeDocument(request, data):
|
||||
'''
|
||||
takes {
|
||||
id: string,
|
||||
or
|
||||
ids: [string]
|
||||
item: string
|
||||
}
|
||||
|
||||
if item is passed, remove relation to item
|
||||
otherwise remove document
|
||||
returns {
|
||||
}
|
||||
Removes one or more documents, either from an item or from the database
|
||||
takes {
|
||||
id or ids: string or [string], // one or more document ids
|
||||
item: string // item id (optional)
|
||||
}
|
||||
returns {}
|
||||
notes: If `item` is present, this removes the documents from that item.
|
||||
Otherwise, it removes the documents from the database.
|
||||
see: addDocument, editDocument, findDocument, getDocument, sortDocuments
|
||||
'''
|
||||
response = json_response()
|
||||
|
||||
|
|
@ -253,12 +245,13 @@ actions.register(removeDocument, cache=False)
|
|||
@login_required_json
|
||||
def sortDocuments(request, data):
|
||||
'''
|
||||
takes {
|
||||
item: string
|
||||
ids: [string]
|
||||
}
|
||||
returns {
|
||||
}
|
||||
Sets the sort order for the documents related to a given item
|
||||
takes {
|
||||
item: string, // item id
|
||||
ids: [string] // list of document ids
|
||||
}
|
||||
returns {}
|
||||
see: addDocument, editDocument, findDocument, removeDocument, sortDocuments
|
||||
'''
|
||||
index = 0
|
||||
item = Item.objects.get(public_id=data['item'])
|
||||
|
|
|
|||
|
|
@ -244,14 +244,16 @@ actions.register(getEdit)
|
|||
@login_required_json
|
||||
def addEdit(request, data):
|
||||
'''
|
||||
takes {
|
||||
[name],
|
||||
[type]
|
||||
}
|
||||
returns {
|
||||
id
|
||||
...
|
||||
}
|
||||
Adds an edit
|
||||
takes {
|
||||
name: string, // name (optional)
|
||||
type: string // 'static' or 'smart'
|
||||
}
|
||||
returns {
|
||||
id: string // edit id
|
||||
... // more edit properties
|
||||
}
|
||||
see: editEdit, findEdit, removeEdit, sortEdits
|
||||
'''
|
||||
data['name'] = re.sub(' \[\d+\]$', '', data.get('name', 'Untitled')).strip()
|
||||
name = data['name']
|
||||
|
|
@ -299,12 +301,18 @@ actions.register(addEdit, cache=False)
|
|||
@login_required_json
|
||||
def editEdit(request, data):
|
||||
'''
|
||||
takes {
|
||||
id
|
||||
}
|
||||
returns {
|
||||
...
|
||||
}
|
||||
Edits an edit (yes!)
|
||||
takes {
|
||||
id: string, // edit id
|
||||
key: value, // property id and new value
|
||||
... // more key/value pairs
|
||||
}
|
||||
returns {
|
||||
id: string, // edit id
|
||||
key: value, // property id and new value
|
||||
... // more key/value pairs
|
||||
}
|
||||
see: addEdit, findEdit, removeEdit, sortEdits
|
||||
'''
|
||||
edit = get_edit_or_404_json(data['id'])
|
||||
response = json_response()
|
||||
|
|
@ -324,12 +332,12 @@ actions.register(editEdit, cache=False)
|
|||
@login_required_json
|
||||
def removeEdit(request, data):
|
||||
'''
|
||||
takes {
|
||||
...
|
||||
}
|
||||
returns {
|
||||
...
|
||||
}
|
||||
Removes an edit
|
||||
takes {
|
||||
id: string // edit id
|
||||
}
|
||||
returns {}
|
||||
see: addEdit, editEdit findEdit, sortEdits
|
||||
'''
|
||||
edit = get_edit_or_404_json(data['id'])
|
||||
response = json_response()
|
||||
|
|
@ -373,32 +381,27 @@ def parse_query(data, user):
|
|||
|
||||
def findEdits(request, data):
|
||||
'''
|
||||
takes {
|
||||
query: {
|
||||
conditions: [
|
||||
{
|
||||
key: 'user',
|
||||
value: 'something',
|
||||
operator: '='
|
||||
}
|
||||
]
|
||||
operator: ","
|
||||
},
|
||||
sort: [{key: 'name', operator: '+'}],
|
||||
range: [0, 100]
|
||||
keys: []
|
||||
}
|
||||
Finds edits for a given query
|
||||
takes {
|
||||
query: object, // query object, see `find`
|
||||
sort: [], // list of sort objects, see `find`
|
||||
range: [int, int], // range of results
|
||||
keys: [string] // list of properties to return
|
||||
}
|
||||
|
||||
possible query keys:
|
||||
name, user, featured, subscribed
|
||||
possible query keys:
|
||||
name, user, featured, subscribed
|
||||
|
||||
possible keys:
|
||||
name, user, featured, subscribed, query
|
||||
possible keys:
|
||||
name, user, featured, subscribed, query
|
||||
|
||||
}
|
||||
returns {
|
||||
items: [object]
|
||||
}
|
||||
}
|
||||
returns {
|
||||
items: [object]
|
||||
}
|
||||
notes: Possible query keys are 'featured', 'name', 'subscribed' and 'user',
|
||||
possible keys are 'featured', 'name', 'query', 'subscribed' and 'user'.
|
||||
see: editEdits, find, removeEdit, sortEdits
|
||||
'''
|
||||
query = parse_query(data, request.user)
|
||||
|
||||
|
|
@ -437,10 +440,13 @@ actions.register(findEdits)
|
|||
@login_required_json
|
||||
def subscribeToEdit(request, data):
|
||||
'''
|
||||
takes {
|
||||
id: string,
|
||||
}
|
||||
returns {}
|
||||
Adds an edit to favorites
|
||||
takes {
|
||||
id: string, // edit id
|
||||
user: string // username (admin-only)
|
||||
}
|
||||
returns {}
|
||||
see: unsubscribeFromEdit
|
||||
'''
|
||||
edit = get_edit_or_404_json(data['id'])
|
||||
user = request.user
|
||||
|
|
@ -461,11 +467,12 @@ actions.register(subscribeToEdit, cache=False)
|
|||
@login_required_json
|
||||
def unsubscribeFromEdit(request, data):
|
||||
'''
|
||||
takes {
|
||||
id: string,
|
||||
user: username(only admins)
|
||||
}
|
||||
returns {}
|
||||
takes {
|
||||
id: string, // edit id
|
||||
user: string // username (admin-only)
|
||||
}
|
||||
returns {}
|
||||
see: subscribeToEdit
|
||||
'''
|
||||
edit = get_edit_or_404_json(data['id'])
|
||||
user = request.user
|
||||
|
|
@ -480,14 +487,13 @@ actions.register(unsubscribeFromEdit, cache=False)
|
|||
@login_required_json
|
||||
def sortEdits(request, data):
|
||||
'''
|
||||
takes {
|
||||
section: 'personal',
|
||||
ids: [1,2,4,3]
|
||||
}
|
||||
known sections: 'personal', 'public', 'featured'
|
||||
featured can only be edited by admins
|
||||
|
||||
returns {}
|
||||
takes {
|
||||
section: string, // 'personal', 'favorite' or 'featured'
|
||||
ids: [string] // ordered list of edit ids
|
||||
}
|
||||
returns {}
|
||||
notes: Sorting featured edits requires a specific per-user capability
|
||||
see: editEdits, findEdits, removeEdit
|
||||
'''
|
||||
position = 0
|
||||
section = data['section']
|
||||
|
|
|
|||
|
|
@ -103,7 +103,7 @@ def find(request, data):
|
|||
Finds items for a given query
|
||||
takes {
|
||||
clipsQuery: object, // clips query object (optional)
|
||||
group: string, // item key to group elements by
|
||||
group: string, // item key to group results by (optional)
|
||||
keys: [string], // list of keys to return, [] for all (optional)
|
||||
positions: [string], // list of item ids (optional)
|
||||
query: { // query object
|
||||
|
|
@ -125,34 +125,34 @@ def find(request, data):
|
|||
operator: string // sort order, '+' or '-'
|
||||
}]
|
||||
}
|
||||
returns { // if `keys` is present (returns items)
|
||||
items: [
|
||||
returns { // if `keys` is present
|
||||
items: [ // returns list of matching items
|
||||
{
|
||||
id: string, // item id
|
||||
... // more item properties
|
||||
},
|
||||
... // more items
|
||||
]
|
||||
} or { // if `clipsQuery` is present (returns clips)
|
||||
clips: [
|
||||
} or { // if `clipsQuery` is present
|
||||
clips: [ // returns list of matching clips
|
||||
{
|
||||
id: string, // clip id
|
||||
... // more clip properties
|
||||
},
|
||||
... // more clips
|
||||
]
|
||||
} or { if `group` is present (returns results for filters)
|
||||
items: [
|
||||
} or { // if `group` is present
|
||||
items: [ // returns results for filters
|
||||
{
|
||||
name: string, // value for item key specified as group
|
||||
items: int // number of matches
|
||||
},
|
||||
... // more group objects
|
||||
]
|
||||
} or { // if `keys` is missing (returns totals)
|
||||
items: int // total number of items
|
||||
} or { // if `positions` is present (returns positions of given items)
|
||||
positions: {
|
||||
} or { // if `keys` is missing
|
||||
items: int // returns total number of items
|
||||
} or { // if `positions` is present ()
|
||||
positions: { // returns positions of given items
|
||||
id: position, // position of the item, per current sort order
|
||||
... // more id/position pairs
|
||||
}
|
||||
|
|
@ -160,7 +160,7 @@ def find(request, data):
|
|||
notes: Comparison operators are '=' (contains) '==' (is), '^' (starts with),
|
||||
'$' (ends with), '<', '<=', '>', or '>=', each optionally prefixed with '!'
|
||||
(not).
|
||||
see: add, edit, remove
|
||||
see: add, edit, get, lookup, remove, upload
|
||||
'''
|
||||
if settings.JSON_DEBUG:
|
||||
print json.dumps(data, indent=2)
|
||||
|
|
@ -288,13 +288,14 @@ def autocomplete(request, data):
|
|||
takes {
|
||||
key: string,
|
||||
value: string,
|
||||
operator: string // '=', '==', '^', '$'
|
||||
query: object // item query to limit results
|
||||
operator: string, // '=', '==', '^', '$'
|
||||
query: object, // item query to limit results, see `find`
|
||||
range: [int, int]
|
||||
}
|
||||
returns {
|
||||
items: [string, ...] // array of matching values
|
||||
}
|
||||
see: autocompleteEntities
|
||||
'''
|
||||
if not 'range' in data:
|
||||
data['range'] = [0, 10]
|
||||
|
|
@ -348,6 +349,7 @@ actions.register(autocomplete)
|
|||
|
||||
def findId(request, data):
|
||||
'''
|
||||
Undocumented
|
||||
takes {
|
||||
'id': string
|
||||
'title': string
|
||||
|
|
@ -378,14 +380,16 @@ def getMetadata(request, data):
|
|||
'''
|
||||
Gets metadata from an external service
|
||||
takes {
|
||||
id: string,
|
||||
keys: [string]
|
||||
id: string, // item id
|
||||
keys: [string] // list of item keys to return
|
||||
}
|
||||
|
||||
returns {
|
||||
key: value
|
||||
..
|
||||
key: value // item key and value
|
||||
... // more key/value pairs
|
||||
}
|
||||
notes: This can be used to populate metadata from a remote source, like
|
||||
IMDb.
|
||||
see: getIds, updateExternalData
|
||||
'''
|
||||
response = json_response({})
|
||||
if settings.DATA_SERVICE:
|
||||
|
|
@ -408,20 +412,23 @@ actions.register(getMetadata)
|
|||
|
||||
def getIds(request, data):
|
||||
'''
|
||||
takes {
|
||||
title: string,
|
||||
director: [string],
|
||||
year: int
|
||||
}
|
||||
|
||||
returns {
|
||||
items: [{
|
||||
tite: string,
|
||||
director: [string],
|
||||
year: int,
|
||||
originalTitle: string
|
||||
}]
|
||||
}
|
||||
Gets ids from an external service
|
||||
takes {
|
||||
title: string, // title
|
||||
director: [string], // list of directors
|
||||
year: int // year
|
||||
}
|
||||
returns {
|
||||
items: [{
|
||||
title: string, // title
|
||||
director: [string], // list of directors
|
||||
year: int, // year
|
||||
originalTitle: string // original title
|
||||
}]
|
||||
}
|
||||
notes: This can be used to populate metadata from a remote source, like
|
||||
IMDb.
|
||||
see: getMetadata, updateExternalData
|
||||
'''
|
||||
response = json_response({})
|
||||
if settings.DATA_SERVICE:
|
||||
|
|
@ -435,13 +442,16 @@ actions.register(getIds)
|
|||
|
||||
def get(request, data):
|
||||
'''
|
||||
takes {
|
||||
id: string,
|
||||
keys: [string]
|
||||
}
|
||||
returns {
|
||||
key: value
|
||||
}
|
||||
Gets an item by id
|
||||
takes {
|
||||
id: string, // item id
|
||||
keys: [string] // item properties to return
|
||||
}
|
||||
returns {
|
||||
key: value, // item key and value
|
||||
... // more key/value pairs
|
||||
}
|
||||
see: add, edit, find, lookup, remove, upload
|
||||
'''
|
||||
response = json_response({})
|
||||
data['keys'] = data.get('keys', [])
|
||||
|
|
@ -478,14 +488,14 @@ def add(request, data):
|
|||
'''
|
||||
Adds a new item (without video)
|
||||
takes {
|
||||
title: string, // item title (optional)
|
||||
title: string, // title (optional)
|
||||
}
|
||||
returns {
|
||||
id: string, // item id
|
||||
title: string, // item title
|
||||
title: string, // title
|
||||
... // more item properties
|
||||
}
|
||||
see: edit, find, get, remove, upload
|
||||
see: edit, find, get, lookup, remove, upload
|
||||
'''
|
||||
if not request.user.get_profile().capability('canAddItems'):
|
||||
response = json_response(status=403, text='permissino denied')
|
||||
|
|
@ -511,14 +521,14 @@ def edit(request, data):
|
|||
Edits metadata of an item
|
||||
takes {
|
||||
id: string, // item id
|
||||
key: value, // property id and new value
|
||||
key: value, // item key and new value
|
||||
... // more key/value pairs
|
||||
}
|
||||
returns {
|
||||
key: value // property id and new value
|
||||
key: value // item key and new value
|
||||
... // more key/value pairs
|
||||
}
|
||||
see: add, find, get, remove, upload
|
||||
see: add, find, get, lookup, remove, upload
|
||||
'''
|
||||
update_clips = False
|
||||
item = get_object_or_404_json(models.Item, public_id=data['id'])
|
||||
|
|
@ -561,13 +571,12 @@ actions.register(edit, cache=False)
|
|||
def remove(request, data):
|
||||
'''
|
||||
Removes an item
|
||||
remove item with id, return status is 200/removed on sucess or 403/permission deinied.
|
||||
takes {
|
||||
id: string // item id
|
||||
}
|
||||
returns {}
|
||||
notes: The return status is 200 for success or 403 for permission denied.
|
||||
see: add, edit, find, get, upload
|
||||
see: add, edit, find, get, lookup, upload
|
||||
'''
|
||||
response = json_response({})
|
||||
item = get_object_or_404_json(models.Item, public_id=data['id'])
|
||||
|
|
@ -593,6 +602,7 @@ def setPosterFrame(request, data):
|
|||
position: float // position in seconds
|
||||
}
|
||||
returns {}
|
||||
see: setPoster
|
||||
'''
|
||||
item = get_object_or_404_json(models.Item, public_id=data['id'])
|
||||
if item.editable(request.user):
|
||||
|
|
@ -621,6 +631,7 @@ def setPoster(request, data):
|
|||
width: int // width in px
|
||||
}
|
||||
}
|
||||
see: setPosterFrame
|
||||
'''
|
||||
item = get_object_or_404_json(models.Item, public_id=data['id'])
|
||||
response = json_response()
|
||||
|
|
@ -649,6 +660,9 @@ def updateExternalData(request, data):
|
|||
id: string // item id
|
||||
}
|
||||
returns {}
|
||||
notes: This can be used to populate metadata from a remote source, like
|
||||
IMDb.
|
||||
see: getIds, getMetadata
|
||||
'''
|
||||
item = get_object_or_404_json(models.Item, public_id=data['id'])
|
||||
response = json_response()
|
||||
|
|
@ -674,6 +688,7 @@ def lookup(request, data):
|
|||
title: string, // title
|
||||
year: string // year
|
||||
}
|
||||
see: add, edit, find, get, remove, upload
|
||||
'''
|
||||
if 'id' in data:
|
||||
i = models.Item.objects.get(public_id=data['id'])
|
||||
|
|
|
|||
Loading…
Reference in a new issue