update api docs

This commit is contained in:
rolux 2014-12-18 20:16:41 +00:00
parent 0a56268b92
commit 6bd001a10a
6 changed files with 213 additions and 280 deletions

View file

@ -44,6 +44,7 @@ actions.register(removeVolume, cache=False)
@login_required_json
def update(request, data):
'''
Undocumented
2 steps:
send files
{volume: 'Videos', files: [{oshash:, path:, mtime:, ,,}]}
@ -110,16 +111,17 @@ actions.register(update, cache=False)
@login_required_json
def upload(request, data=None):
'''
Uploads one or more media files for a given item
takes {
id: string
frame: [] //multipart frames
file: [] //multipart file
id: string // item id
frame: [] // one or more frames
file: [] // one or more files
}
returns {
info: object,
rename: object
info: object, // undocumented
rename: object // undocumented
}
see: add, edit, find, get, lookup, remove
'''
response = json_response({})
f = get_object_or_404_json(models.File, oshash=request.POST['id'])
@ -157,15 +159,17 @@ actions.register(upload, cache=False)
@login_required_json
def addMedia(request, data):
'''
Adds media files to a given item
takes {
id: oshash
filename: string,
item: string
info: {}
filename: string, // undocumented
id: oshash, // undocumented
info: {}, // undocumented
item: string // item id
}
returns {
item: id,
item: id // item id
}
see: editMedia, moveMedia, removeMedia
'''
response = json_response({})
oshash = data.pop('id')
@ -333,7 +337,7 @@ def taskStatus(request, data):
status: string, // status, 'PENDING' or 'OK'
result: object // result data
}
notes: To be deprecated, will be wrapped in regular API call
notes: To be deprecated, will be wrapped in regular API call.
'''
#FIXME: should check if user has permissions to get status
if 'taskId' in data:
@ -348,14 +352,14 @@ actions.register(taskStatus, cache=False)
@login_required_json
def moveMedia(request, data):
'''
change file / item link
Move media files from one item to another
takes {
ids: ids of files
item: new public_id
}
returns {
}
returns {}
notes: This will *not* (yet) shift the corresponding annotations.
see: addMedia, editMedia, findMedia, removeMedia
'''
if Item.objects.filter(public_id=data['item']).count() == 1:
i = Item.objects.get(public_id=data['item'])
@ -395,17 +399,21 @@ actions.register(moveMedia, cache=False)
@login_required_json
def editMedia(request, data):
'''
change file / item link
Edits one or more media files
takes {
files: [
{id:, key1: value1, key2: value2}
...
{
id: string, // file id
key: value, // property id and new value
... more key/value pairs
},
// more media files
]
}
possible keys: part, partTitle, language, ignore, extension, version, episodes
returns {
}
returns {}
notes: Possible keys are 'episodes', 'extension', 'ignore', 'language',
'part', 'partTitle' and 'version'.
see: addMedia, findMedia, moveMedia, removeMedia
'''
ignore = []
save_items = []
@ -452,6 +460,12 @@ actions.register(editMedia, cache=False)
@login_required_json
def removeMedia(request, data):
'''
Removes one or more media files from a given item
takes {} // undocumented
returns {} // undocumented
see: addMedia, editMedia, findMedia, moveMedia
'''
response = json_response()
if request.user.get_profile().get_level() == 'admin':
qs = models.File.objects.filter(oshash__in=data['ids'], instances__id=None)
@ -471,11 +485,11 @@ actions.register(removeMedia, cache=False)
def getPath(request, data):
'''
Undocumented
change file / item link
takes {
id: [hash of file]
}
returns {
id: path
}
@ -527,77 +541,16 @@ def _order_query(qs, sort, prefix=''):
def findMedia(request, data):
'''
Finds media files
takes {
'query': query,
'sort': array,
'range': array
query: object, // query object, see `find`
sort: array, // list of sort objects, see `find`
range: [int, int] // range of results to return
}
query: item query object, more on query syntax at
https://wiki.0x2620.org/wiki/pandora/QuerySyntax
get media for all items matching the given query
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: [object]
}
Groups
takes {
'query': query,
'key': string,
'group': string,
'range': array
}
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: path, items
with keys
items contains list of {'path': string, 'items': int}:
returns {
items: [object]
}
without keys: return number of items in given query
returns {
items: int
}
Positions
takes {
'query': query,
'positions': [string]
}
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
}
items: [object] // list of items
}
see: addMedia, editMedia, moveMedia, removeMedia
'''
if not data.get('sort'):
data['sort'] = [{'key': 'path', 'operator': '+'}]
@ -664,11 +617,12 @@ actions.register(findMedia)
def parsePath(request, data): #parse path and return info
'''
Parses a path
takes {
path: string
path: string // undocumented
}
returns {
imdb: string
imdb: string // undocumented
}
'''
path = data['path']
@ -678,12 +632,13 @@ actions.register(parsePath)
def getMediaInfo(request, data):
'''
Gets media file info, undocumented
takes {
id: oshash of stream file
id: string // oshash of media file
}
returns {
item: public_id,
file: oshash of source file
item: string, // item id
file: string // oshash of source file
}
'''
f = None

View file

@ -19,14 +19,14 @@ import models
@login_required_json
def addEvent(request, data):
'''
Adds a calendar event
Adds a new calendar event
takes {
name: string,
start: string,
end: string
end: string, // 'YYYY-MM-DD HH:MM:SS', arbitrary precision
name: string, // name
start: string // 'YYYY-MM-DD HH:MM:SS', arbitrary precision
}
returns {
id: string
id: string // event id
}
see: editEvent, findEvents, removeEvents
'''
@ -73,14 +73,15 @@ def editEvent(request, data):
'''
Edits a calendar event
takes {
id: string,
name: string,
start: string,
end: string
end: string, // 'YYYY-MM-DD HH:MM:SS', arbitrary precision
id: string, // event id
name: string, // event name
start: string // 'YYYY-MM-DD HH:MM:SS', arbitrary precision
}
returns {
id: string,
...
id: string, // event id
key: value, // property id and value
... // more key/value pairs
}
see: addEvent, findEvents, removeEvent
'''
@ -176,43 +177,14 @@ def findEvents(request, data):
'''
Finds calendar events
takes {
query: object,
sort: array
range': [int, int]
query: object, // query object, see `find`
sort: [object], // list of sort objects, see `find`
range: [int, int] // range of results to return
}
query: query object, more on query syntax at
https://wiki.0x2620.org/wiki/pandora/QuerySyntax
itemsQuery: {
//see find request
},
sort: array of key, operator dics
[
{
key: "year",
operator: "-"
},
{
key: "director",
operator: ""
returns {
items: [object] // list of items
}
]
range: result range, array [from, to]
itemsQuery can be used to limit the resuts to matches in those items.
with keys, items is list of dicts with requested properties:
returns {'status': {'code': int, 'text': string},
'data': {items: array}}
Positions
takes {
query: object,
ids: [string]
}
query: query object, more on query syntax at
https://wiki.0x2620.org/wiki/pandora/QuerySyntax
ids: ids of events for which positions are required
see: addEvent, editEvent, removeEvent
'''
response = json_response(status=200, text='ok')
query = parse_query(data, request.user)

View file

@ -499,6 +499,7 @@ def add(request, data):
title: string, // title
... // more item properties
}
notes: To allow for this, set config option `itemRequiresVideo` to false
see: edit, find, get, lookup, remove, upload
'''
if not request.user.get_profile().capability('canAddItems'):

View file

@ -141,12 +141,12 @@ def addListItems(request, data):
'''
Adds one or more items to a list
takes {
list: listId,
items: [itemId],
query: ...
}
returns {
list: string, // list id
items: [string], // either list of item ids
query: object // or query object, see `find`
}
returns {}
see: find, orderListItems, removeListItems
'''
list = get_list_or_404_json(data['list'])
if 'items' in data:
@ -171,12 +171,12 @@ def removeListItems(request, data):
'''
Removes one or more items from a list
takes {
list: listId,
items: [itemId],
quert: ...
}
returns {
list: string, // list id
items: [itemId], // either list of item ids
query: object // or query object, see `find`
}
returns {}
see: addListItems, find, orderListItems
'''
list = get_list_or_404_json(data['list'])
if 'items' in data:
@ -197,14 +197,14 @@ actions.register(removeListItems, cache=False)
@login_required_json
def orderListItems(request, data):
'''
Sets the manual order of items in a given list
Sets the manual orderings of items in a given list
takes {
list: string
ids: [string]
}
returns {
list: string, // list id
ids: [string] // ordered list of item ids
}
returns {}
notes: There is no UI for this yet.
see: addListItems, removeListItems
'''
list = get_list_or_404_json(data['list'])
response = json_response()
@ -225,22 +225,16 @@ def addList(request, data):
'''
Adds a new list
takes {
name: value,
name: value, // list name (optional)
... // more key/value pairs
}
possible keys to create list:
name
description
type
query
items
view
sort
returns {
id: string,
name: string,
...
id: string, // list id
name: string, // list name
... // more key/value pairs
}
notes: Possible keys are 'description', 'items', 'name', 'query', 'sort',
'type' and 'view'.
see: editList, findLists, getList, removeList, sortLists
'''
data['name'] = re.sub(' \[\d+\]$', '', data.get('name', 'Untitled')).strip()
@ -287,18 +281,18 @@ def editList(request, data):
'''
Edits a list
takes {
id: listId,
key: value,
id: string, // list id
key: value, // property id and new value
... // more key/value pairs
}
keys: name, status, query, position, posterFrames
if you change status you have to provide position of list
posterFrames:
array with objects that have item/position
returns {
id: string,
...
id: string, // list id
... // more key/value pairs
}
notes: Possible keys are 'name', 'position', 'posterFrames', 'query' and
'status'. 'posterFrames' is an array of {item, position}. If you change
'status', you have to pass 'position' (the position of the list in its new
list folder).
see: addList, findLists, getList, removeList, sortLists
'''
list = get_list_or_404_json(data['id'])
@ -339,7 +333,8 @@ def subscribeToList(request, data):
'''
Adds a list to favorites
takes {
id: listId,
id: string, // list id
user: string // username (admin-only)
}
returns {}
see: unsubscribeFromList
@ -365,8 +360,8 @@ def unsubscribeFromList(request, data):
'''
Removes a list from favorites
takes {
id: listId,
user: username(only admins)
id: string, // list id
user: string // username (admin-only)
}
returns {}
see: subscribeToList
@ -386,12 +381,12 @@ def sortLists(request, data):
'''
Set order of lists
takes {
section: 'personal',
ids: [1,2,4,3]
section: string, // lists section
ids: [string] // ordered list of lists
}
known sections: 'personal', 'public', 'featured'
featured can only be edited by admins
returns {}
notes: Possible sections are 'personal', 'favorite' and 'featured'. Setting
the order of featured lists requires the appropriate capability.
'''
position = 0
section = data['section']

View file

@ -15,21 +15,25 @@ import models
def getNews(request, data):
'''
Gets one or all news items
takes {
id: string
id: string // news item id (optional)
}
returns {
id: string,
...
}
if not id is passed, return all news items
takes {}
returns {
items: [object]
returns { // if `id` is present
id: string, // news item id
key: value, // property id and value
... // more key/value pairs
} or { // if `id` is missing
items: [
{
id: string, // news item id
key: value, // property id and value
... // more key/value pairs
},
... // more news items
]
}
see: addNews, editNews, removeNews
'''
response = json_response()
if 'id' in data:
@ -44,15 +48,17 @@ actions.register(getNews)
@login_required_json
def addNews(request, data):
'''
Adds a new news item
takes {
title: string,
date: string,
text: text,
date: string, // date (format undocumented)
text: text, // text
title: string // title
}
returns {
id: string,
...
id: string, // news item id
... // more key/value pairs
}
see: editNews, getNews, removeNews
'''
news = models.News()
for key in ('title', 'text', 'date'):
@ -67,10 +73,12 @@ actions.register(addNews, cache=False)
@login_required_json
def removeNews(request, data):
'''
Removes a news item
takes {
id: id
id: string // news item id
}
returns {}
see: addNews, editNews, getNews
'''
response = json_response({})
news = get_object_or_404_json(models.News, id=ox.fromAZ(data['id']))
@ -86,16 +94,18 @@ actions.register(removeNews, cache=False)
@login_required_json
def editNews(request, data):
'''
Edits a news item
takes {
id: string,
title: string,
text: string,
date: string
date: string, // date (format undocumented)
id: string, // news item id
text: string, // text
title: string // title
}
returns {
id: string
...
}
see: addNews, getNews, removeNews
'''
response = json_response({})
n = get_object_or_404_json(models.News, id=ox.fromAZ(data['id']))

View file

@ -20,7 +20,7 @@ import models
@login_required_json
def addPlace(request, data):
'''
Adds a place
Adds a new place
takes {
name: "",
alternativeNames: [],