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
pandora
annotation
app
archive
changelog
clip
document
edit
entity
event
item
itemlist
log
news
person
title

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()

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

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': '+'}]

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()

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()

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`

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']

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)

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)

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:

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)

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()

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
''' '''

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()

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()