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-19 15:05:08 +00:00
parent 5ac0c04d37
commit cada20f904
15 changed files with 186 additions and 282 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
pandora/annotation/views.py
View File

@ -90,7 +90,7 @@ def findAnnotations(request, data):
... // more annotation properties
}]
}
see: addAnnotation, addAnnotations, editAnnotation, getAnnotation,
see: addAnnotation, addAnnotations, editAnnotation, find, getAnnotation,
removeAnnotation
'''
response = json_response()

80
pandora/app/views.py
View File

@ -96,13 +96,15 @@ def robots_txt(request, url):
def getPage(request, data):
'''
takes {
name: pagename
}
returns {
name:
text:
}
Gets the text/html for a given site page (like 'About')
takes {
name: string // page id
}
returns {
name: string, // page id
text: string // text/html
}
see: editPage
'''
if isinstance(data, basestring):
name = data
@ -120,14 +122,16 @@ actions.register(getPage)
@login_required_json
def editPage(request, data):
'''
takes {
name: pagename
text: text
}
returns {
name:
text:
}
Edits a site page (like 'About')
takes {
name: string, // page id
text: string // new text/html
}
returns {
name: string, // page id
text: string // new text/html
}
see: getPage
'''
if request.user.get_profile().capability('canEditSitePages'):
page, created = models.Page.objects.get_or_create(name=data['name'])
@ -143,10 +147,12 @@ actions.register(editPage)
def init(request, data):
'''
takes {}
returns {
user: object
}
Makes an init request
takes {}
returns {
site: object, // site data
user: object // user data
}
'''
response = json_response({})
config = copy.deepcopy(settings.CONFIG)
@ -162,16 +168,16 @@ actions.register(init)
def embedURL(request, data):
'''
takes {
url
maxwidth
maxheight
}
returns {
html
...
}
Returns HTML to embed a given URL
takes {
url: string, // URL
maxwidth: int, // max width in px
maxheight: int // max height in px
}
returns {
html: string // HTML
}
see: getEmbedDefaults
'''
response = json_response({})
response['data'] = ox.get_embed_code(data['url'], data.get('maxwidth'), data.get('maxheight'))
@ -180,19 +186,21 @@ actions.register(embedURL)
def getEmbedDefaults(request, data):
'''
takes {}
Returns embed default values
takes {}
returns {
document: str // first document, sorted by id
edit: str // first edit, sorted by name
editDuration: float // duration of that edit
item: str // first item, sorted by id
document: string, // first document, sorted by id
edit: string, // first edit, sorted by name
editDuration: float, // duration of that edit
item: string, // first item, sorted by id
itemDuration: float // duration of that item
itemRatio: float // video ratio of that item
list: str // first list, sorted by name
text: str // first text, sorted by name
list: string // first list, sorted by name
text: string // first text, sorted by name
videoRatio: float // pandora.site.video.previewRatio
videoResolution: int // largest value in pandora.site.video.resolutions
}
see: embedURL
'''
from document.models import Document
from item.models import Item

6
pandora/archive/views.py
View File

@ -169,7 +169,7 @@ def addMedia(request, data):
returns {
item: id // item id
}
see: editMedia, moveMedia, removeMedia
see: editMedia, findMedia, moveMedia, removeMedia
'''
response = json_response({})
oshash = data.pop('id')
@ -399,7 +399,7 @@ actions.register(moveMedia, cache=False)
@login_required_json
def editMedia(request, data):
'''
Edits one or more media files
Edits data for one or more media files
takes {
files: [
{
@ -550,7 +550,7 @@ def findMedia(request, data):
returns {
items: [object] // list of items
}
see: addMedia, editMedia, moveMedia, removeMedia
see: addMedia, editMedia, find, moveMedia, removeMedia
'''
if not data.get('sort'):
data['sort'] = [{'key': 'path', 'operator': '+'}]

30
pandora/changelog/views.py
View File

@ -42,25 +42,17 @@ def order_query(qs, sort):
@capability_required_json('canManageUsers')
def findChangeLogs(request, data):
'''
takes {
query: {
conditions: [
{
key: 'user',
value: 'something',
operator: '='
}
]
operator: ","
},
sort: [{key: 'created', operator: '+'}],
range: [int, int]
keys: [string]
}
returns {
items: [object]
}
Finds changelog entries for a given query
takes {
query: object, // query object, see `find`
sort: [object], // list of sort objects, see `find`
range: [int, int], // range of results to return
keys: [string] // list of properties to return
}
returns {
items: [object] // list of changelog entries
}
see: find
'''
response = json_response()

32
pandora/clip/views.py
View File

@ -74,25 +74,19 @@ def order_query(qs, sort):
def findClips(request, data):
'''
takes {
query: {
conditions: [object],
operator: string // '&' or '|'
},
itemsQuery: {
conditions: [],
operator: string // '&' or '|'
},
keys: [string],
position: int,
positions: [string],
range: [int, int],
sort: []
}
returns {
items: [object]
}
Finds clips for a given query
takes {
query: object, // find clips, query object, see `find`
itemsQuery: object, // limit to matching items, query object, see `find`
keys: [string], // list of properties to return
positions: [int], // list of positions
range: [int, int], // range of results to return
sort: [object] // list of sort objects, see `find`
}
returns {
items: [object] // list of clip objects
}
see: find
'''
response = json_response()

2
pandora/document/views.py
View File

@ -65,6 +65,7 @@ actions.register(addDocument, cache=False)
@login_required_json
def editDocument(request, data):
'''
Edits data for a document
takes {
id: string, // document id
name: string, // new document name
@ -141,6 +142,7 @@ def parse_query(data, user):
def findDocuments(request, data):
'''
Finds documents for a given query
takes {
query: object, // query object, see `find`
sort: [object], // list of sort objects, see `find`

33
pandora/edit/views.py
View File

@ -206,8 +206,7 @@ def sortClips(request, data):
edit: string, // edit id
sort: object // sort
}
returns {
}
returns {}
note: sort is [{key: string, operator: string}], operator can be '+' or '-'
see: addClips, editClip, orderClips, removeClips
'''
@ -220,14 +219,16 @@ actions.register(sortClips, cache=False)
def getEdit(request, data):
'''
Gets an edit by id
takes {
id:
keys: []
id: string, // edit id
keys: [string] // list of properties to return
}
returns {
id:
clips:
id: string, // edit id
clips: [object] // list of clips in this edit
}
see: addEdit, editEdits, findEdits, removeEdit, sortEdits
'''
if 'id' in data:
response = json_response()
@ -253,7 +254,7 @@ def addEdit(request, data):
id: string // edit id
... // more edit properties
}
see: editEdit, findEdit, removeEdit, sortEdits
see: editEdit, findEdit, getEdit, removeEdit, sortEdits
'''
data['name'] = re.sub(' \[\d+\]$', '', data.get('name', 'Untitled')).strip()
name = data['name']
@ -312,7 +313,7 @@ def editEdit(request, data):
key: value, // property id and new value
... // more key/value pairs
}
see: addEdit, findEdit, removeEdit, sortEdits
see: addEdit, findEdit, getEdit, removeEdit, sortEdits
'''
edit = get_edit_or_404_json(data['id'])
response = json_response()
@ -337,7 +338,7 @@ def removeEdit(request, data):
id: string // edit id
}
returns {}
see: addEdit, editEdit findEdit, sortEdits
see: addEdit, editEdit, findEdit, getEdit, sortEdits
'''
edit = get_edit_or_404_json(data['id'])
response = json_response()
@ -388,20 +389,12 @@ def findEdits(request, data):
range: [int, int], // range of results
keys: [string] // list of properties to return
}
possible query keys:
name, user, featured, subscribed
possible keys:
name, user, featured, subscribed, query
}
returns {
items: [object]
items: [object] // list of edit objects
}
notes: Possible query keys are 'featured', 'name', 'subscribed' and 'user',
possible keys are 'featured', 'name', 'query', 'subscribed' and 'user'.
see: editEdits, find, removeEdit, sortEdits
see: addEdit, editEdits, find, getEdit, removeEdit, sortEdits
'''
query = parse_query(data, request.user)
@ -494,7 +487,7 @@ def sortEdits(request, data):
}
returns {}
notes: Sorting featured edits requires a specific per-user capability
see: editEdits, findEdits, removeEdit
see: addEdit, editEdits, findEdits, getEdit, removeEdit
'''
position = 0
section = data['section']

12
pandora/entity/views.py
View File

@ -209,18 +209,12 @@ def findEntities(request, data):
range: [int, int], // range of results
keys: [string] // list of properties to return
}
possible query keys:
name, type
possible keys:
name, type, alternativeNames
}
returns {
items: [object]
}
see: addEntity, editEntity, getEntity, removeEntity
notes: Possible query keys are 'name' and 'type', possible keys are
'alternativeNames', 'name' and 'type'.
see: addEntity, editEntity, find, getEntity, removeEntity
'''
query = parse_query(data, request.user)

2
pandora/event/views.py
View File

@ -184,7 +184,7 @@ def findEvents(request, data):
returns {
items: [object] // list of items
}
see: addEvent, editEvent, removeEvent
see: addEvent, editEvent, find, removeEvent
'''
response = json_response(status=200, text='ok')
query = parse_query(data, request.user)

4
pandora/item/views.py
View File

@ -161,10 +161,10 @@ def find(request, data):
'$' (ends with), '<', '<=', '>', or '>=', each optionally prefixed with '!'
(not).
Leaving out `keys` or passing `positions` can be useful when building a
responsive GUI: First leave out `keys` to get totals as fast as possible,
responsive UI: First leave out `keys` to get totals as fast as possible,
then pass `positions` to get the positions of previously selected items,
finally make the query with `keys` and an appropriate range.
For more examples, see the <a href="https://wiki.0x2620.org/wiki/pandora/QuerySyntax">0x2620.org wiki</a>.
For more examples, see https://wiki.0x2620.org/wiki/pandora/QuerySyntax.
see: add, edit, get, lookup, remove, upload
'''
if settings.JSON_DEBUG:

19
pandora/itemlist/views.py
View File

@ -58,24 +58,19 @@ def parse_query(data, user):
def findLists(request, data):
'''
Finds lists 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] // properties to return
}
possible query keys:
name, user, featured, subscribed
possible keys:
name, user, featured, subscribed, query
range: [int, int], // range of results to return
keys: [string] // list of properties to return
}
returns {
items: [{name: string, user: string, featured: bool, public...}]
items: [object] // list of list objects
}
see: addList, editList, getList, removeList, sortLists
notes: Possible query keys are 'featured', 'name', 'subscribed' and 'user',
possible keys are 'featured', 'name', 'query', 'subscribed' and 'user'.
see: addList, editList, find, getList, removeList, sortLists
'''
query = parse_query(data, request.user)

55
pandora/log/views.py
View File

@ -17,13 +17,14 @@ import models
def logError(request, data):
'''
takes {
url: string,
line: string,
text: string
}
returns {
}
Logs an error
takes {
url: string, // URL
line: string, // line number
text: string // error text
}
returns {}
see: findErrorLogs, removeErrorLogs
'''
if request.user.is_authenticated():
user = request.user
@ -49,10 +50,12 @@ actions.register(logError, cache=False)
@admin_required_json
def removeErrorLogs(request, data):
'''
takes {
ids: [string]
}
returns {}
Removes entries from the error log
takes {
ids: [string] // list of error ids
}
returns {}
see: findErrorLogs, logError
'''
models.Log.objects.filter(id__in=[ox.fromAZ(i) for i in data['ids']]).delete()
response = json_response()
@ -86,25 +89,17 @@ def order_query(qs, sort):
@admin_required_json
def findErrorLogs(request, data):
'''
takes {
query: {
conditions: [
{
key: 'user',
value: 'something',
operator: '='
}
]
operator: ","
},
sort: [{key: 'created', operator: '+'}],
range: [int, int]
keys: [string]
}
returns {
items: [object]
}
Finds error logs for a given query
takes {
query: object, // query object, see `find`
sort: [object], // list of sort objects, see `find`
range: [int, int], // range of results to return
keys: [string] // list of properties to return
}
returns {
items: [object]
}
see: find, logError, removeErrorLogs
'''
response = json_response()

4
pandora/news/views.py
View File

@ -102,8 +102,8 @@ def editNews(request, data):
title: string // title
}
returns {
id: string
...
id: string // news item id
... // more properties
}
see: addNews, getNews, removeNews
'''

102
pandora/person/views.py
View File

@ -19,15 +19,17 @@ from changelog.models import add_changelog
@capability_required_json('canManageTitlesAndNames')
def editName(request, data):
'''
takes {
id: id,
sortname: string
}
returns {
id: string,
name: string
...
}
Edits the sort name for a given name
takes {
id: string, // name id
sortname: string // sort name
}
returns {
id: string, // name id
name: string // name
... // more properties
}
see: findNames, sortName
'''
person = get_object_or_404_json(models.Person, pk=ox.fromAZ(data['id']))
response = json_response()
@ -43,14 +45,16 @@ actions.register(editName, cache=False)
def sortName(request, data):
'''
get sort name(s) for given name or names
takes {
names: [string]
name: string
}
returns {
name: sortName
}
Gets the sort name for one or more names
takes {
name: string, // either name
names: [string] // or list of names
}
returns {
name: sortName, // sort name for this name
... // more results
}
see editName, findNames
'''
names = data.get('names', [])
if 'name' in data:
@ -92,56 +96,20 @@ def order_query(qs, sort):
def findNames(request, data):
'''
takes {
query: {
conditions: [
{
key: 'user',
value: 'something',
operator: '='
}
]
operator: ","
},
itemsQuery: {
//see find request
},
sort: [{key: 'name', operator: '+'}],
range: [0, 100]
keys: []
}
possible query keys:
name, numberofnames
possible keys:
name, sortname, numberofnames
returns {
items: [{name:, user:, featured:, public...}]
}
param data
{'query': query, 'sort': array, 'range': array}
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]
with keys, items is list of dicts with requested properties:
returns {
items: [string]
}
Finds names for a given query
takes {
query: object, // query object, see `find`
itemsQuery: object, // limit to matched items, query object, see `find`
sort: [object], // list of sort objects, see `find`
range: [int, int], // range of results to return
keys: [string] // list of properties to return
}
returns {
items: [object] // list of name objects
}
notes: Possible query keys are 'name' and 'numberofnames', possible keys
are 'name', 'numberofnames' and 'sortname'.
see: editName, find, sortName
'''
response = json_response()

85
pandora/title/views.py
View File

@ -20,14 +20,16 @@ import models
@capability_required_json('canManageTitlesAndNames')
def editTitle(request, data):
'''
takes {
id: string
sorttitle: string
}
can contain any of the allowed keys for title
returns {
id: string
}
Edits the sort title for a given title
takes {
id: string, // name id
sorttitle: string // sort title
}
returns {
id: string, // title id
... // more properties
}
see: findTitles
'''
title = get_object_or_404_json(models.Title, pk=ox.fromAZ(data['id']))
response = json_response()
@ -71,59 +73,20 @@ def order_query(qs, sort):
def findTitles(request, data):
'''
takes {
query: {
conditions: [
{
key: 'user',
value: 'something',
operator: '='
}
]
operator: ","
},
itemsQuery: {
//see find request
},
sort: [{key: 'title', operator: '+'}],
range: [0, 100]
keys: []
}
possible query keys:
title, numberoftitles
possible keys:
title, sorttitle, numberoftitles
returns {
items: [object]
}
takes {
query: object,
sort: [object],
range: [int, int]
}
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]
with keys, items is list of dicts with requested properties:
returns {items: [object]}
Finds titles for a given query
takes {
query: object, // query object, see `find`
itemsQuery: object, // limit to matched items, query object, see `find`
sort: [object], // list of sort objects, see `find`
range: [int, int], // range of results to return
keys: [string] // list of properties to return
}
returns {
items: [object] // list of title objects
}
notes: Possible query keys are 'numberoftitles' and 'title', possible keys
are 'numberoftitles', 'sorttitle' and 'title'.
see: editTitle, find
'''
response = json_response()