update api docs

This commit is contained in:
rolux 2014-12-18 18:18:18 +00:00
parent 9c28041171
commit 7cfdf7b8db
3 changed files with 192 additions and 178 deletions

View file

@ -29,16 +29,13 @@ def get_document_or_404_json(id):
@login_required_json
def addDocument(request, data):
'''
add document(s) to item
Adds one or more documents to one or more items
takes {
item: string or [string]
id: string
or
ids: [string]
}
returns {
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:
@ -69,15 +66,19 @@ actions.register(addDocument, cache=False)
def editDocument(request, data):
'''
takes {
id: string
name: string
description: string
item(optional): edit descriptoin per item
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
@ -141,31 +142,21 @@ 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
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: [object]
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):
'''
Gets a document by id
takes {
id: string,
keys: [string]
id: string, // document id
keys: [string] // list of properties to return
}
returns {
key: value
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):
'''
Removes one or more documents, either from an item or from the database
takes {
id: string,
or
ids: [string]
item: string
}
if item is passed, remove relation to item
otherwise remove document
returns {
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):
'''
Sets the sort order for the documents related to a given item
takes {
item: string
ids: [string]
}
returns {
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'])

View file

@ -244,14 +244,16 @@ actions.register(getEdit)
@login_required_json
def addEdit(request, data):
'''
Adds an edit
takes {
[name],
[type]
name: string, // name (optional)
type: string // 'static' or 'smart'
}
returns {
id
...
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):
'''
Edits an edit (yes!)
takes {
id
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):
'''
Removes an edit
takes {
...
}
returns {
...
id: string // edit id
}
returns {}
see: addEdit, editEdit findEdit, sortEdits
'''
edit = get_edit_or_404_json(data['id'])
response = json_response()
@ -373,20 +381,12 @@ def parse_query(data, user):
def findEdits(request, data):
'''
Finds edits for a given query
takes {
query: {
conditions: [
{
key: 'user',
value: 'something',
operator: '='
}
]
operator: ","
},
sort: [{key: 'name', operator: '+'}],
range: [0, 100]
keys: []
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:
@ -399,6 +399,9 @@ def findEdits(request, data):
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):
'''
Adds an edit to favorites
takes {
id: string,
id: string, // edit id
user: string // username (admin-only)
}
returns {}
see: unsubscribeFromEdit
'''
edit = get_edit_or_404_json(data['id'])
user = request.user
@ -462,10 +468,11 @@ actions.register(subscribeToEdit, cache=False)
def unsubscribeFromEdit(request, data):
'''
takes {
id: string,
user: username(only admins)
id: string, // edit id
user: string // username (admin-only)
}
returns {}
see: subscribeToEdit
'''
edit = get_edit_or_404_json(data['id'])
user = request.user
@ -481,13 +488,12 @@ actions.register(unsubscribeFromEdit, cache=False)
def sortEdits(request, data):
'''
takes {
section: 'personal',
ids: [1,2,4,3]
section: string, // 'personal', 'favorite' or 'featured'
ids: [string] // ordered list of edit ids
}
known sections: 'personal', 'public', 'featured'
featured can only be edited by admins
returns {}
notes: Sorting featured edits requires a specific per-user capability
see: editEdits, findEdits, removeEdit
'''
position = 0
section = data['section']

View file

@ -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):
'''
Gets ids from an external service
takes {
title: string,
director: [string],
year: int
title: string, // title
director: [string], // list of directors
year: int // year
}
returns {
items: [{
tite: string,
director: [string],
year: int,
originalTitle: string
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):
'''
Gets an item by id
takes {
id: string,
keys: [string]
id: string, // item id
keys: [string] // item properties to return
}
returns {
key: value
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'])