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-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 ... // more annotation properties
}] }]
} }
see: addAnnotation, addAnnotations, editAnnotation, getAnnotation, see: addAnnotation, addAnnotations, editAnnotation, find, getAnnotation,
removeAnnotation removeAnnotation
''' '''
response = json_response() response = json_response()

80
pandora/app/views.py
View file

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

6
pandora/archive/views.py
View file

@ -169,7 +169,7 @@ def addMedia(request, data):
returns { returns {
item: id // item id item: id // item id
} }
see: editMedia, moveMedia, removeMedia see: editMedia, findMedia, moveMedia, removeMedia
''' '''
response = json_response({}) response = json_response({})
oshash = data.pop('id') oshash = data.pop('id')
@ -399,7 +399,7 @@ actions.register(moveMedia, cache=False)
@login_required_json @login_required_json
def editMedia(request, data): def editMedia(request, data):
''' '''
Edits one or more media files Edits data for one or more media files
takes { takes {
files: [ files: [
{ {
@ -550,7 +550,7 @@ def findMedia(request, data):
returns { returns {
items: [object] // list of items items: [object] // list of items
} }
see: addMedia, editMedia, moveMedia, removeMedia see: addMedia, editMedia, find, moveMedia, removeMedia
''' '''
if not data.get('sort'): if not data.get('sort'):
data['sort'] = [{'key': 'path', 'operator': '+'}] 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') @capability_required_json('canManageUsers')
def findChangeLogs(request, data): def findChangeLogs(request, data):
''' '''
takes { Finds changelog entries for a given query
query: { takes {
conditions: [ query: object, // query object, see `find`
{ sort: [object], // list of sort objects, see `find`
key: 'user', range: [int, int], // range of results to return
value: 'something', keys: [string] // list of properties to return
operator: '=' }
} returns {
] items: [object] // list of changelog entries
operator: "," }
}, see: find
sort: [{key: 'created', operator: '+'}],
range: [int, int]
keys: [string]
}
returns {
items: [object]
}
''' '''
response = json_response() response = json_response()

32
pandora/clip/views.py
View file

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

2
pandora/document/views.py
View file

@ -65,6 +65,7 @@ actions.register(addDocument, cache=False)
@login_required_json @login_required_json
def editDocument(request, data): def editDocument(request, data):
''' '''
Edits data for a document
takes { takes {
id: string, // document id id: string, // document id
name: string, // new document name name: string, // new document name
@ -141,6 +142,7 @@ def parse_query(data, user):
def findDocuments(request, data): def findDocuments(request, data):
''' '''
Finds documents for a given query
takes { takes {
query: object, // query object, see `find` query: object, // query object, see `find`
sort: [object], // list of sort objects, 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 edit: string, // edit id
sort: object // sort sort: object // sort
} }
returns { returns {}
}
note: sort is [{key: string, operator: string}], operator can be '+' or '-' note: sort is [{key: string, operator: string}], operator can be '+' or '-'
see: addClips, editClip, orderClips, removeClips see: addClips, editClip, orderClips, removeClips
''' '''
@ -220,14 +219,16 @@ actions.register(sortClips, cache=False)
def getEdit(request, data): def getEdit(request, data):
''' '''
Gets an edit by id
takes { takes {
id: id: string, // edit id
keys: [] keys: [string] // list of properties to return
} }
returns { returns {
id: id: string, // edit id
clips: clips: [object] // list of clips in this edit
} }
see: addEdit, editEdits, findEdits, removeEdit, sortEdits
''' '''
if 'id' in data: if 'id' in data:
response = json_response() response = json_response()
@ -253,7 +254,7 @@ def addEdit(request, data):
id: string // edit id id: string // edit id
... // more edit properties ... // more edit properties
} }
see: editEdit, findEdit, removeEdit, sortEdits see: editEdit, findEdit, getEdit, 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']
@ -312,7 +313,7 @@ def editEdit(request, data):
key: value, // property id and new value key: value, // property id and new value
... // more key/value pairs ... // more key/value pairs
} }
see: addEdit, findEdit, removeEdit, sortEdits see: addEdit, findEdit, getEdit, removeEdit, sortEdits
''' '''
edit = get_edit_or_404_json(data['id']) edit = get_edit_or_404_json(data['id'])
response = json_response() response = json_response()
@ -337,7 +338,7 @@ def removeEdit(request, data):
id: string // edit id id: string // edit id
} }
returns {} returns {}
see: addEdit, editEdit findEdit, sortEdits see: addEdit, editEdit, findEdit, getEdit, sortEdits
''' '''
edit = get_edit_or_404_json(data['id']) edit = get_edit_or_404_json(data['id'])
response = json_response() response = json_response()
@ -388,20 +389,12 @@ def findEdits(request, data):
range: [int, int], // range of results range: [int, int], // range of results
keys: [string] // list of properties to return keys: [string] // list of properties to return
} }
possible query keys:
name, user, featured, subscribed
possible keys:
name, user, featured, subscribed, query
}
returns { returns {
items: [object] items: [object] // list of edit objects
} }
notes: Possible query keys are 'featured', 'name', 'subscribed' and 'user', notes: Possible query keys are 'featured', 'name', 'subscribed' and 'user',
possible keys are 'featured', 'name', 'query', '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) query = parse_query(data, request.user)
@ -494,7 +487,7 @@ def sortEdits(request, data):
} }
returns {} returns {}
notes: Sorting featured edits requires a specific per-user capability notes: Sorting featured edits requires a specific per-user capability
see: editEdits, findEdits, removeEdit see: addEdit, editEdits, findEdits, getEdit, removeEdit
''' '''
position = 0 position = 0
section = data['section'] section = data['section']

12
pandora/entity/views.py
View file

@ -209,18 +209,12 @@ def findEntities(request, data):
range: [int, int], // range of results range: [int, int], // range of results
keys: [string] // list of properties to return keys: [string] // list of properties to return
} }
possible query keys:
name, type
possible keys:
name, type, alternativeNames
}
returns { returns {
items: [object] 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) query = parse_query(data, request.user)

2
pandora/event/views.py
View file

@ -184,7 +184,7 @@ def findEvents(request, data):
returns { returns {
items: [object] // list of items items: [object] // list of items
} }
see: addEvent, editEvent, removeEvent see: addEvent, editEvent, find, removeEvent
''' '''
response = json_response(status=200, text='ok') response = json_response(status=200, text='ok')
query = parse_query(data, request.user) 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 '!' '$' (ends with), '<', '<=', '>', or '>=', each optionally prefixed with '!'
(not). (not).
Leaving out `keys` or passing `positions` can be useful when building a 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, then pass `positions` to get the positions of previously selected items,
finally make the query with `keys` and an appropriate range. 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 see: add, edit, get, lookup, remove, upload
''' '''
if settings.JSON_DEBUG: if settings.JSON_DEBUG:

19
pandora/itemlist/views.py
View file

@ -58,24 +58,19 @@ def parse_query(data, user):
def findLists(request, data): def findLists(request, data):
''' '''
Finds lists for a given query
takes { takes {
query: object, // query object, see `find` query: object, // query object, see `find`
sort: [], // list of sort objects, see `find` sort: [], // list of sort objects, see `find`
range: [int, int], // range of results range: [int, int], // range of results to return
keys: [string] // properties to return keys: [string] // list of properties to return
}
possible query keys:
name, user, featured, subscribed
possible keys:
name, user, featured, subscribed, query
} }
returns { 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) query = parse_query(data, request.user)

55
pandora/log/views.py
View file

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

4
pandora/news/views.py
View file

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

85
pandora/title/views.py
View file

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