0x2620/pandora
2
1
Fork 1
Code Issues 1.3k Pull requests Releases Wiki Activity

update api docs

Browse source
This commit is contained in:
rolux 2014-12-18 16:39:47 +00:00
parent 379fb0f478
commit 8fd99ac1be
3 changed files with 120 additions and 180 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

49
pandora/annotation/views.py
View file

@ -74,35 +74,24 @@ def order_query(qs, sort):
def findAnnotations(request, data): def findAnnotations(request, data):
''' '''
Finds annotations for a given query
takes { takes {
query: { query: object, // annotation query object, see `find`
conditions: [{ itemsQuery: object, // item query object, see `find`
key: string, keys: [string, string, ...], // list of keys to return, see `find`
operator: string,
value: string
}],
operator: string // '&' or '|'
},
itemsQuery: {
conditions: [{
key: string,
operator: string,
value: string
}],
operator: string // '&' or '|'
},
keys: [],
position: int, position: int,
positions: [], positions: [string, string], // list of item ids, see `find`
range: [int, int], range: [int, int], // items to return, per current sort order, see `find`
sort: [] sort: [] // list of sort object, see `find`
} }
returns { returns {
annotations: [{ annotations: [{
id: string, id: string, // annotation id
... ... // more annotation properties
}] }]
} }
see: addAnnotation, addAnnotations, editAnnotation, getAnnotation,
removeAnnotation
''' '''
response = json_response() response = json_response()
@ -138,8 +127,8 @@ def getAnnotation(request, data):
keys: [string] // list of keys to return keys: [string] // list of keys to return
} }
returns { returns {
key: value, key: value, // property id and value
... ... // more key/value pairs
} }
''' '''
response = json_response({}) response = json_response({})
@ -164,7 +153,7 @@ def addAnnotation(request, data):
id: string, // annotation id id: string, // annotation id
... // more annotation properties ... // more annotation properties
} }
see: addAnnotation, editAnnotation, findAnnotations, getAnnotation, see: addAnnotations, editAnnotation, findAnnotations, getAnnotation,
getTaskStatus, removeAnnotation getTaskStatus, removeAnnotation
''' '''
for key in ('item', 'layer', 'in', 'out', 'value'): for key in ('item', 'layer', 'in', 'out', 'value'):
@ -252,9 +241,9 @@ def removeAnnotation(request, data):
takes { takes {
id: string // annotation id id: string // annotation id
} }
returns { returns {}
} see: addAnnotation, addAnnotations, editAnnotation, findAnnotations,
FIXME: returns nothing? getAnnotation
''' '''
response = json_response({}) response = json_response({})
a = get_object_or_404_json(models.Annotation, public_id=data['id']) a = get_object_or_404_json(models.Annotation, public_id=data['id'])
@ -279,8 +268,10 @@ def editAnnotation(request, data):
} }
returns { returns {
id: string, // annotation id id: string, // annotation id
... ... // more annotation properties
} }
see: addAnnotation, addAnnotations, findAnnotations, getAnnotation,
removeAnnotation
''' '''
response = json_response({}) response = json_response({})
a = get_object_or_404_json(models.Annotation, public_id=data['id']) a = get_object_or_404_json(models.Annotation, public_id=data['id'])

2
pandora/edit/views.py
View file

@ -31,7 +31,7 @@ def addClips(request, data):
Adds one or more clips to an edit Adds one or more clips to an edit
takes { takes {
edit: string, // edit id, edit: string, // edit id,
index: integer, // position within edit (optional), index: int, // position within edit (optional),
clips: [ clips: [
{ {
item: string, // item id item: string, // item id

249
pandora/item/views.py
View file

@ -100,120 +100,67 @@ def parse_query(data, user):
def find(request, data): def find(request, data):
''' '''
Finds items Finds items for a given query
takes { takes {
clipsQuery: ..., clipsQuery: object, // clips query object (optional)
keys: [string], // list of keys to return (optional) group: string, // item key to group elements by
keys: [string], // list of keys to return, [] for all (optional)
positions: [string], // list of item ids (optional) positions: [string], // list of item ids (optional)
query: { // query object query: { // query object
conditions: [{ // list of condition objects conditions: [{ // list of condition objects...
key: string, key: string, // item key
operator: string, // comparison operator, see below operator: string, // comparison operator, see below
value: string value: string // value
}, { // or query objects (nested subconditions) }, { // ... or query objects (nested subconditions)
query: { query: {
conditions: [{}], conditions: [object, ...], // list of condition objects
operator: string operator: string // comparison operator, see below
} }
}], }],
operator: string // logical operator, '&' or '|' operator: string // logical operator, '&' or '|'
}, },
range: [int, int] // items to return, per current sort order
sort: [{ // list of sort objects sort: [{ // list of sort objects
key: string, // item key key: string, // item key
operator: string // sort order, '+' or '-' operator: string // sort order, '+' or '-'
}],
range: [int, int] // from, to
}
returns {
items: [{
id: string, // item id
...
}] }]
} or { // if `keys` is missing
items: int // total number of items
} or { // if `positions` is set
...
} }
Comparison operators are '=' (contains) '==' (is), '^' (starts with), returns { // if `keys` is present (returns items)
items: [
{
id: string, // item id
... // more item properties
},
... // more items
]
} or { // if `clipsQuery` is present (returns clips)
clips: [
{
id: string, // clip id
... // more clip properties
},
... // more clips
]
} or { if `group` is present (returns results for filters)
items: [
{
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: {
id: position, // position of the item, per current sort order
... // more id/position pairs
}
}
notes: Comparison operators are '=' (contains) '==' (is), '^' (starts with),
'$' (ends with), '<', '<=', '>', or '>=', each optionally prefixed with '!' '$' (ends with), '<', '<=', '>', or '>=', each optionally prefixed with '!'
(not). (not).
see: add, edit, remove
Example:
find({
query:{
conditions:[{ key: '*', value: 'paris', operator: '='}],
operator:'&'
},
keys: ['title', 'id'],
range: [0, 10],
sort: [{key: 'title', operator: '+'}]
})
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]
keys: array of keys to return
group: group elements by, country, genre, director...
with keys, items is list of dicts with requested properties:
returns {
items: [objects]
}
Groups
takes {
'query': query,
'key': string,
'group': string,
'range': array
clips: {}
}
query: query object, more on query syntax at
https://wiki.0x2620.org/wiki/pandora/QuerySyntax
range: result range, array [from, to]
keys: array of keys to return
group: group elements by, country, genre, director...
possible values for keys: name, items
with keys
items contains list of {'name': string, 'items': int}:
returns {
items: [objects]
}
without keys: return number of items in given query
returns {
items: int
}
Positions
takes {
'query': query,
'positions': [],
'sort': array
}
query: query object, more on query syntax at
https://wiki.0x2620.org/wiki/pandora/QuerySyntax
positions: ids of items for which positions are required
returns {
positions: {
id: position
}
}
''' '''
if settings.JSON_DEBUG: if settings.JSON_DEBUG:
print json.dumps(data, indent=2) print json.dumps(data, indent=2)
@ -561,18 +508,17 @@ actions.register(add, cache=False)
@login_required_json @login_required_json
def edit(request, data): def edit(request, data):
''' '''
edit item with id, you can pass one or many key/value pairs, Edits metadata of an item
returns all key/values for edited item. takes {
id: string, // item id
takes { key: value, // property id and new value
id: string, ... // more key/value pairs
key: value, }
... returns {
} key: value // property id and new value
returns { ... // more key/value pairs
key: value }
.. see: add, find, get, remove, upload
}
''' '''
update_clips = False update_clips = False
item = get_object_or_404_json(models.Item, public_id=data['id']) item = get_object_or_404_json(models.Item, public_id=data['id'])
@ -614,13 +560,14 @@ actions.register(edit, cache=False)
@login_required_json @login_required_json
def remove(request, data): def remove(request, data):
''' '''
remove item with id, return status is 200/removed on sucess or 403/permission deinied. Removes an item
takes { remove item with id, return status is 200/removed on sucess or 403/permission deinied.
id: string takes {
} id: string // item id
}
returns { returns {}
} notes: The return status is 200 for success or 403 for permission denied.
see: add, edit, find, get, upload
''' '''
response = json_response({}) response = json_response({})
item = get_object_or_404_json(models.Item, public_id=data['id']) item = get_object_or_404_json(models.Item, public_id=data['id'])
@ -640,12 +587,12 @@ actions.register(remove, cache=False)
def setPosterFrame(request, data): def setPosterFrame(request, data):
''' '''
takes { Sets the poster frame for an item
id: string, takes {
position: float id: string, // item id
} position: float // position in seconds
returns { }
} returns {}
''' '''
item = get_object_or_404_json(models.Item, public_id=data['id']) item = get_object_or_404_json(models.Item, public_id=data['id'])
if item.editable(request.user): if item.editable(request.user):
@ -662,17 +609,18 @@ actions.register(setPosterFrame, cache=False)
def setPoster(request, data): def setPoster(request, data):
''' '''
takes { Sets the poster for an item
id: string, takes {
source: string // url id: string, // item id
} source: string // poster url
returns { }
poster: { returns {
url: string, poster: {
width: int, height: int, // height in px
height: int url: string, // poster url
} width: int // width in px
} }
}
''' '''
item = get_object_or_404_json(models.Item, public_id=data['id']) item = get_object_or_404_json(models.Item, public_id=data['id'])
response = json_response() response = json_response()
@ -696,11 +644,11 @@ actions.register(setPoster, cache=False)
def updateExternalData(request, data): def updateExternalData(request, data):
''' '''
takes { Updates metadata from an external service
id: string, takes {
} id: string // item id
returns { }
} returns {}
''' '''
item = get_object_or_404_json(models.Item, public_id=data['id']) item = get_object_or_404_json(models.Item, public_id=data['id'])
response = json_response() response = json_response()
@ -713,18 +661,19 @@ actions.register(updateExternalData, cache=False)
def lookup(request, data): def lookup(request, data):
''' '''
takes { Looks up an item given partial metadata
title: string, takes {
director: [string], director: [string], // directors (optional)
year: string, id: string, // item id (optional)
id: string title: string, // title (optional)
} year: string // year (optional)
returns { }
title: string, returns {
director: [string], director: [string], // director
year: string, id: string, // item id
id: string title: string, // title
} year: string // year
}
''' '''
if 'id' in data: if 'id' in data:
i = models.Item.objects.get(public_id=data['id']) i = models.Item.objects.get(public_id=data['id'])