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

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

133
pandora/document/views.py
View File

@ -29,16 +29,13 @@ def get_document_or_404_json(id):
@login_required_json @login_required_json
def addDocument(request, data): def addDocument(request, data):
''' '''
add document(s) to item Adds one or more documents to one or more items
takes { takes {
item: string or [string] item: string or [string], // one or more item ids
id: string or [string] // one or more document ids
id: string }
or returns {}
ids: [string] see: editDocument, findDocument, getDocument, removeDocument, sortDocuments
}
returns {
}
''' '''
response = json_response() response = json_response()
if 'ids' in data: if 'ids' in data:
@ -68,16 +65,20 @@ actions.register(addDocument, cache=False)
@login_required_json @login_required_json
def editDocument(request, data): def editDocument(request, data):
''' '''
takes { takes {
id: string id: string, // document id
name: string name: string, // new document name
description: string description: string // new document description
item(optional): edit descriptoin per item item: string // item id (optional)
} }
returns { returns {
id: 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() response = json_response()
item = 'item' in data and Item.objects.get(public_id=data['item']) or None 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): def findDocuments(request, data):
''' '''
takes { takes {
query: { query: object, // query object, see `find`
conditions: [ sort: [object], // list of sort objects, see `find`
{ range: [int, int], // range of results, per current sort order
key: 'user', keys: [string] // list of keys to return
value: 'something', }
operator: '=' returns {
} items: [{ // list of documents
] key: value, // item key and value
operator: "," ... // more key/value pairs
}, }]
sort: [{key: 'name', operator: '+'}], }
range: [0, 100] Notes: Query keys and keys to be returned can be 'extension', 'name',
keys: [] 'size' and 'user'.
} see: addDocument, editDocument, find, getDocument, removeDocument,
sortDocuments
possible query keys:
name, user, extension, size
possible keys:
name, user, extension, size
}
returns {
items: [object]
}
''' '''
query = parse_query(data, request.user) query = parse_query(data, request.user)
@ -193,13 +184,16 @@ actions.register(findDocuments)
def getDocument(request, data): def getDocument(request, data):
''' '''
takes { Gets a document by id
id: string, takes {
keys: [string] id: string, // document id
} keys: [string] // list of properties to return
returns { }
key: value returns {
} key: value, // document key and value
... // more key/value pairs
}
see: addDocument, editDocument, findDocument, removeDocument, sortDocuments
''' '''
response = json_response({}) response = json_response({})
data['keys'] = data.get('keys', []) data['keys'] = data.get('keys', [])
@ -211,17 +205,15 @@ actions.register(getDocument)
@login_required_json @login_required_json
def removeDocument(request, data): def removeDocument(request, data):
''' '''
takes { Removes one or more documents, either from an item or from the database
id: string, takes {
or id or ids: string or [string], // one or more document ids
ids: [string] item: string // item id (optional)
item: string }
} returns {}
notes: If `item` is present, this removes the documents from that item.
if item is passed, remove relation to item Otherwise, it removes the documents from the database.
otherwise remove document see: addDocument, editDocument, findDocument, getDocument, sortDocuments
returns {
}
''' '''
response = json_response() response = json_response()
@ -253,12 +245,13 @@ actions.register(removeDocument, cache=False)
@login_required_json @login_required_json
def sortDocuments(request, data): def sortDocuments(request, data):
''' '''
takes { Sets the sort order for the documents related to a given item
item: string takes {
ids: [string] item: string, // item id
} ids: [string] // list of document ids
returns { }
} returns {}
see: addDocument, editDocument, findDocument, removeDocument, sortDocuments
''' '''
index = 0 index = 0
item = Item.objects.get(public_id=data['item']) item = Item.objects.get(public_id=data['item'])

126
pandora/edit/views.py
View File

@ -244,14 +244,16 @@ actions.register(getEdit)
@login_required_json @login_required_json
def addEdit(request, data): def addEdit(request, data):
''' '''
takes { Adds an edit
[name], takes {
[type] name: string, // name (optional)
} type: string // 'static' or 'smart'
returns { }
id returns {
... id: string // edit id
} ... // more edit properties
}
see: editEdit, findEdit, removeEdit, sortEdits
''' '''
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']
@ -299,12 +301,18 @@ actions.register(addEdit, cache=False)
@login_required_json @login_required_json
def editEdit(request, data): def editEdit(request, data):
''' '''
takes { Edits an edit (yes!)
id takes {
} id: string, // edit id
returns { 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']) edit = get_edit_or_404_json(data['id'])
response = json_response() response = json_response()
@ -324,12 +332,12 @@ actions.register(editEdit, cache=False)
@login_required_json @login_required_json
def removeEdit(request, data): def removeEdit(request, data):
''' '''
takes { Removes an edit
... takes {
} id: string // edit id
returns { }
... returns {}
} see: addEdit, editEdit findEdit, sortEdits
''' '''
edit = get_edit_or_404_json(data['id']) edit = get_edit_or_404_json(data['id'])
response = json_response() response = json_response()
@ -373,32 +381,27 @@ def parse_query(data, user):
def findEdits(request, data): def findEdits(request, data):
''' '''
takes { Finds edits for a given query
query: { takes {
conditions: [ query: object, // query object, see `find`
{ sort: [], // list of sort objects, see `find`
key: 'user', range: [int, int], // range of results
value: 'something', keys: [string] // list of properties to return
operator: '=' }
}
]
operator: ","
},
sort: [{key: 'name', operator: '+'}],
range: [0, 100]
keys: []
}
possible query keys: possible query keys:
name, user, featured, subscribed name, user, featured, subscribed
possible keys: possible keys:
name, user, featured, subscribed, query name, user, featured, subscribed, query
} }
returns { returns {
items: [object] 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) query = parse_query(data, request.user)
@ -437,10 +440,13 @@ actions.register(findEdits)
@login_required_json @login_required_json
def subscribeToEdit(request, data): def subscribeToEdit(request, data):
''' '''
takes { Adds an edit to favorites
id: string, takes {
} id: string, // edit id
returns {} user: string // username (admin-only)
}
returns {}
see: unsubscribeFromEdit
''' '''
edit = get_edit_or_404_json(data['id']) edit = get_edit_or_404_json(data['id'])
user = request.user user = request.user
@ -461,11 +467,12 @@ actions.register(subscribeToEdit, cache=False)
@login_required_json @login_required_json
def unsubscribeFromEdit(request, data): def unsubscribeFromEdit(request, data):
''' '''
takes { takes {
id: string, id: string, // edit id
user: username(only admins) user: string // username (admin-only)
} }
returns {} returns {}
see: subscribeToEdit
''' '''
edit = get_edit_or_404_json(data['id']) edit = get_edit_or_404_json(data['id'])
user = request.user user = request.user
@ -480,14 +487,13 @@ actions.register(unsubscribeFromEdit, cache=False)
@login_required_json @login_required_json
def sortEdits(request, data): def sortEdits(request, data):
''' '''
takes { takes {
section: 'personal', section: string, // 'personal', 'favorite' or 'featured'
ids: [1,2,4,3] ids: [string] // ordered list of edit ids
} }
known sections: 'personal', 'public', 'featured' returns {}
featured can only be edited by admins notes: Sorting featured edits requires a specific per-user capability
see: editEdits, findEdits, removeEdit
returns {}
''' '''
position = 0 position = 0
section = data['section'] section = data['section']

111
pandora/item/views.py
View File

@ -103,7 +103,7 @@ def find(request, data):
Finds items for a given query Finds items for a given query
takes { takes {
clipsQuery: object, // clips query object (optional) 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) 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
@ -125,34 +125,34 @@ def find(request, data):
operator: string // sort order, '+' or '-' operator: string // sort order, '+' or '-'
}] }]
} }
returns { // if `keys` is present (returns items) returns { // if `keys` is present
items: [ items: [ // returns list of matching items
{ {
id: string, // item id id: string, // item id
... // more item properties ... // more item properties
}, },
... // more items ... // more items
] ]
} or { // if `clipsQuery` is present (returns clips) } or { // if `clipsQuery` is present
clips: [ clips: [ // returns list of matching clips
{ {
id: string, // clip id id: string, // clip id
... // more clip properties ... // more clip properties
}, },
... // more clips ... // more clips
] ]
} or { if `group` is present (returns results for filters) } or { // if `group` is present
items: [ items: [ // returns results for filters
{ {
name: string, // value for item key specified as group name: string, // value for item key specified as group
items: int // number of matches items: int // number of matches
}, },
... // more group objects ... // more group objects
] ]
} or { // if `keys` is missing (returns totals) } or { // if `keys` is missing
items: int // total number of items items: int // returns total number of items
} or { // if `positions` is present (returns positions of given items) } or { // if `positions` is present ()
positions: { positions: { // returns positions of given items
id: position, // position of the item, per current sort order id: position, // position of the item, per current sort order
... // more id/position pairs ... // more id/position pairs
} }
@ -160,7 +160,7 @@ def find(request, data):
notes: Comparison operators are '=' (contains) '==' (is), '^' (starts with), 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 see: add, edit, get, lookup, remove, upload
''' '''
if settings.JSON_DEBUG: if settings.JSON_DEBUG:
print json.dumps(data, indent=2) print json.dumps(data, indent=2)
@ -288,13 +288,14 @@ def autocomplete(request, data):
takes { takes {
key: string, key: string,
value: string, value: string,
operator: string // '=', '==', '^', '$' operator: string, // '=', '==', '^', '$'
query: object // item query to limit results query: object, // item query to limit results, see `find`
range: [int, int] range: [int, int]
} }
returns { returns {
items: [string, ...] // array of matching values items: [string, ...] // array of matching values
} }
see: autocompleteEntities
''' '''
if not 'range' in data: if not 'range' in data:
data['range'] = [0, 10] data['range'] = [0, 10]
@ -348,6 +349,7 @@ actions.register(autocomplete)
def findId(request, data): def findId(request, data):
''' '''
Undocumented
takes { takes {
'id': string 'id': string
'title': string 'title': string
@ -378,14 +380,16 @@ def getMetadata(request, data):
''' '''
Gets metadata from an external service Gets metadata from an external service
takes { takes {
id: string, id: string, // item id
keys: [string] keys: [string] // list of item keys to return
} }
returns { 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({}) response = json_response({})
if settings.DATA_SERVICE: if settings.DATA_SERVICE:
@ -408,20 +412,23 @@ actions.register(getMetadata)
def getIds(request, data): def getIds(request, data):
''' '''
takes { Gets ids from an external service
title: string, takes {
director: [string], title: string, // title
year: int director: [string], // list of directors
} year: int // year
}
returns { returns {
items: [{ items: [{
tite: string, title: string, // title
director: [string], director: [string], // list of directors
year: int, year: int, // year
originalTitle: string originalTitle: string // original title
}] }]
} }
notes: This can be used to populate metadata from a remote source, like
IMDb.
see: getMetadata, updateExternalData
''' '''
response = json_response({}) response = json_response({})
if settings.DATA_SERVICE: if settings.DATA_SERVICE:
@ -435,13 +442,16 @@ actions.register(getIds)
def get(request, data): def get(request, data):
''' '''
takes { Gets an item by id
id: string, takes {
keys: [string] id: string, // item id
} keys: [string] // item properties to return
returns { }
key: value returns {
} key: value, // item key and value
... // more key/value pairs
}
see: add, edit, find, lookup, remove, upload
''' '''
response = json_response({}) response = json_response({})
data['keys'] = data.get('keys', []) data['keys'] = data.get('keys', [])
@ -478,14 +488,14 @@ def add(request, data):
''' '''
Adds a new item (without video) Adds a new item (without video)
takes { takes {
title: string, // item title (optional) title: string, // title (optional)
} }
returns { returns {
id: string, // item id id: string, // item id
title: string, // item title title: string, // title
... // more item properties ... // more item properties
} }
see: edit, find, get, remove, upload see: edit, find, get, lookup, remove, upload
''' '''
if not request.user.get_profile().capability('canAddItems'): if not request.user.get_profile().capability('canAddItems'):
response = json_response(status=403, text='permissino denied') response = json_response(status=403, text='permissino denied')
@ -511,14 +521,14 @@ def edit(request, data):
Edits metadata of an item Edits metadata of an item
takes { takes {
id: string, // item id id: string, // item id
key: value, // property id and new value key: value, // item key and new value
... // more key/value pairs ... // more key/value pairs
} }
returns { returns {
key: value // property id and new value key: value // item key and new value
... // more key/value pairs ... // more key/value pairs
} }
see: add, find, get, remove, upload see: add, find, get, lookup, 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'])
@ -561,13 +571,12 @@ actions.register(edit, cache=False)
def remove(request, data): def remove(request, data):
''' '''
Removes an item Removes an item
remove item with id, return status is 200/removed on sucess or 403/permission deinied.
takes { takes {
id: string // item id id: string // item id
} }
returns {} returns {}
notes: The return status is 200 for success or 403 for permission denied. 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({}) 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'])
@ -593,6 +602,7 @@ def setPosterFrame(request, data):
position: float // position in seconds position: float // position in seconds
} }
returns {} returns {}
see: setPoster
''' '''
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):
@ -621,6 +631,7 @@ def setPoster(request, data):
width: int // width in px width: int // width in px
} }
} }
see: setPosterFrame
''' '''
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()
@ -649,6 +660,9 @@ def updateExternalData(request, data):
id: string // item id id: string // item id
} }
returns {} 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']) item = get_object_or_404_json(models.Item, public_id=data['id'])
response = json_response() response = json_response()
@ -674,6 +688,7 @@ def lookup(request, data):
title: string, // title title: string, // title
year: string // year year: string // year
} }
see: add, edit, find, get, remove, upload
''' '''
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'])