forked from 0x2620/pandora
update api docs
This commit is contained in:
rolux
parent
09b9b1d90e
commit
0a56268b92
6 changed files with 299 additions and 277 deletions
|
|
@ -45,8 +45,9 @@ def addClips(request, data):
|
|||
]
|
||||
}
|
||||
returns {}
|
||||
notes: Clips are either {item, in, out} or {annotation}. If index is
|
||||
missing, clips will be inserted at the end of the edit.
|
||||
notes: Clips are either {item, in, out} (by value) or {annotation} (by
|
||||
reference). If `index` is missing, clips will be inserted at the end of the
|
||||
edit.
|
||||
see: editClip, orderClips, removeClips, sortClips
|
||||
'''
|
||||
response = json_response()
|
||||
|
|
|
|||
|
|
@ -31,14 +31,14 @@ def get_entity_or_404_json(id):
|
|||
@login_required_json
|
||||
def addEntity(request, data):
|
||||
'''
|
||||
add entity
|
||||
takes {
|
||||
type:
|
||||
name:
|
||||
alternativeNames
|
||||
}
|
||||
returns {
|
||||
}
|
||||
Adds an entity
|
||||
takes {
|
||||
type: string,
|
||||
name: string,
|
||||
alternativeNames: [string]
|
||||
}
|
||||
returns {}
|
||||
see: editEntity, findEntities, getEntity, removeEntity
|
||||
'''
|
||||
existing_names = []
|
||||
exists = False
|
||||
|
|
@ -97,6 +97,7 @@ def autocompleteEntities(request, data):
|
|||
returns {
|
||||
items: [{id, name,...}, ...] // array of matching entities
|
||||
}
|
||||
see: autocomplete
|
||||
'''
|
||||
if not 'range' in data:
|
||||
data['range'] = [0, 10]
|
||||
|
|
@ -144,16 +145,18 @@ actions.register(autocompleteEntities)
|
|||
@login_required_json
|
||||
def editEntity(request, data):
|
||||
'''
|
||||
takes {
|
||||
id: string
|
||||
name: string
|
||||
description: string
|
||||
item(optional): edit descriptoin per item
|
||||
}
|
||||
returns {
|
||||
id:
|
||||
...
|
||||
}
|
||||
Edits an entity
|
||||
takes {
|
||||
id: string
|
||||
name: string
|
||||
description: string
|
||||
item(optional): edit descriptoin per item
|
||||
}
|
||||
returns {
|
||||
id:
|
||||
...
|
||||
}
|
||||
see: addEntity, findEntities, getEntity, removeEntity
|
||||
'''
|
||||
response = json_response()
|
||||
entity = get_entity_or_404_json(data['id'])
|
||||
|
|
@ -197,32 +200,25 @@ def parse_query(data, user):
|
|||
|
||||
def findEntities(request, data):
|
||||
'''
|
||||
takes {
|
||||
query: {
|
||||
conditions: [
|
||||
{
|
||||
key: 'name',
|
||||
value: 'something',
|
||||
operator: '='
|
||||
}
|
||||
]
|
||||
operator: ","
|
||||
},
|
||||
sort: [{key: 'name', operator: '+'}],
|
||||
range: [0, 100]
|
||||
keys: []
|
||||
}
|
||||
Finds entities 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
|
||||
keys: [string] // list of properties to return
|
||||
}
|
||||
|
||||
possible query keys:
|
||||
name, type
|
||||
possible query keys:
|
||||
name, type
|
||||
|
||||
possible keys:
|
||||
name, type, alternativeNames
|
||||
possible keys:
|
||||
name, type, alternativeNames
|
||||
|
||||
}
|
||||
returns {
|
||||
items: [object]
|
||||
}
|
||||
}
|
||||
returns {
|
||||
items: [object]
|
||||
}
|
||||
see: addEntity, editEntity, getEntity, removeEntity
|
||||
'''
|
||||
query = parse_query(data, request.user)
|
||||
|
||||
|
|
@ -246,13 +242,15 @@ actions.register(findEntities)
|
|||
|
||||
def getEntity(request, data):
|
||||
'''
|
||||
takes {
|
||||
id: string,
|
||||
keys: [string]
|
||||
}
|
||||
returns {
|
||||
key: value
|
||||
}
|
||||
Gets an entity by id
|
||||
takes {
|
||||
id: string,
|
||||
keys: [string]
|
||||
}
|
||||
returns {
|
||||
key: value
|
||||
}
|
||||
see: addEntity, editEntity, findEntities, removeEntity
|
||||
'''
|
||||
response = json_response({})
|
||||
data['keys'] = data.get('keys', [])
|
||||
|
|
@ -264,13 +262,15 @@ actions.register(getEntity)
|
|||
@login_required_json
|
||||
def removeEntity(request, data):
|
||||
'''
|
||||
takes {
|
||||
id: string,
|
||||
or
|
||||
ids: [string]
|
||||
}
|
||||
returns {
|
||||
}
|
||||
Removes an entity
|
||||
takes {
|
||||
id: string,
|
||||
or
|
||||
ids: [string]
|
||||
}
|
||||
returns {
|
||||
}
|
||||
see: addEntity, editEntity, findEntities, getEntity
|
||||
'''
|
||||
response = json_response()
|
||||
|
||||
|
|
|
|||
|
|
@ -19,14 +19,16 @@ import models
|
|||
@login_required_json
|
||||
def addEvent(request, data):
|
||||
'''
|
||||
takes {
|
||||
name: string,
|
||||
start: string,
|
||||
end: string
|
||||
}
|
||||
returns {
|
||||
id: string
|
||||
}
|
||||
Adds a calendar event
|
||||
takes {
|
||||
name: string,
|
||||
start: string,
|
||||
end: string
|
||||
}
|
||||
returns {
|
||||
id: string
|
||||
}
|
||||
see: editEvent, findEvents, removeEvents
|
||||
'''
|
||||
existing_names = []
|
||||
exists = False
|
||||
|
|
@ -69,16 +71,18 @@ actions.register(addEvent, cache=False)
|
|||
@login_required_json
|
||||
def editEvent(request, data):
|
||||
'''
|
||||
takes {
|
||||
id: string,
|
||||
name: string,
|
||||
start: string,
|
||||
end: string
|
||||
}
|
||||
returns {
|
||||
id: string,
|
||||
...
|
||||
}
|
||||
Edits a calendar event
|
||||
takes {
|
||||
id: string,
|
||||
name: string,
|
||||
start: string,
|
||||
end: string
|
||||
}
|
||||
returns {
|
||||
id: string,
|
||||
...
|
||||
}
|
||||
see: addEvent, findEvents, removeEvent
|
||||
'''
|
||||
event = get_object_or_404_json(models.Event, pk=ox.fromAZ(data['id']))
|
||||
if event.editable(request.user):
|
||||
|
|
@ -123,11 +127,12 @@ actions.register(editEvent, cache=False)
|
|||
@login_required_json
|
||||
def removeEvent(request, data):
|
||||
'''
|
||||
remove Event with given id
|
||||
takes {
|
||||
id: event id
|
||||
}
|
||||
returns {}
|
||||
Removes a calendar event
|
||||
takes {
|
||||
id: event id
|
||||
}
|
||||
returns {}
|
||||
see: addEvent, editEvent, findEvents
|
||||
'''
|
||||
event = get_object_or_404_json(models.Event, pk=ox.fromAZ(data['id']))
|
||||
if event.editable(request.user):
|
||||
|
|
@ -169,11 +174,12 @@ def order_query(qs, sort):
|
|||
|
||||
def findEvents(request, data):
|
||||
'''
|
||||
takes {
|
||||
query: object,
|
||||
sort: array
|
||||
range': [int, int]
|
||||
}
|
||||
Finds calendar events
|
||||
takes {
|
||||
query: object,
|
||||
sort: array
|
||||
range': [int, int]
|
||||
}
|
||||
|
||||
query: query object, more on query syntax at
|
||||
https://wiki.0x2620.org/wiki/pandora/QuerySyntax
|
||||
|
|
@ -238,11 +244,12 @@ actions.register(findEvents)
|
|||
|
||||
def getEventNames(request, data):
|
||||
'''
|
||||
takes {
|
||||
}
|
||||
returns {
|
||||
items: [{name: string, matches: int}]
|
||||
}
|
||||
Undocumented
|
||||
takes {
|
||||
}
|
||||
returns {
|
||||
items: [{name: string, matches: int}]
|
||||
}
|
||||
'''
|
||||
response = json_response({})
|
||||
layers = [l['id'] for l in filter(lambda l: l['type'] == 'event',
|
||||
|
|
|
|||
|
|
@ -160,6 +160,10 @@ def find(request, data):
|
|||
notes: Comparison operators are '=' (contains) '==' (is), '^' (starts with),
|
||||
'$' (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,
|
||||
then pass `positions` to get the positions of previously selected items,
|
||||
finally make the query with `keys` and an appropriate range.
|
||||
see: add, edit, get, lookup, remove, upload
|
||||
'''
|
||||
if settings.JSON_DEBUG:
|
||||
|
|
|
|||
|
|
@ -58,32 +58,24 @@ def parse_query(data, user):
|
|||
|
||||
def findLists(request, data):
|
||||
'''
|
||||
takes {
|
||||
query: {
|
||||
conditions: [
|
||||
{
|
||||
key: 'user',
|
||||
value: 'something',
|
||||
operator: '='
|
||||
}
|
||||
]
|
||||
operator: ","
|
||||
},
|
||||
sort: [{key: 'name', operator: '+'}],
|
||||
range: [0, 100]
|
||||
keys: []
|
||||
}
|
||||
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 query keys:
|
||||
name, user, featured, subscribed
|
||||
|
||||
possible keys:
|
||||
name, user, featured, subscribed, query
|
||||
possible keys:
|
||||
name, user, featured, subscribed, query
|
||||
|
||||
}
|
||||
returns {
|
||||
items: [{name: string, user: string, featured: bool, public...}]
|
||||
}
|
||||
}
|
||||
returns {
|
||||
items: [{name: string, user: string, featured: bool, public...}]
|
||||
}
|
||||
see: addList, editList, getList, removeList, sortLists
|
||||
'''
|
||||
query = parse_query(data, request.user)
|
||||
|
||||
|
|
@ -121,14 +113,16 @@ actions.register(findLists)
|
|||
|
||||
def getList(request, data):
|
||||
'''
|
||||
takes {
|
||||
id: listid
|
||||
}
|
||||
returns {
|
||||
id:
|
||||
section:
|
||||
...
|
||||
}
|
||||
Gets a list by id
|
||||
takes {
|
||||
id: listid
|
||||
}
|
||||
returns {
|
||||
id:
|
||||
section:
|
||||
...
|
||||
}
|
||||
see: addList, editList, findLists, removeList, sortLists
|
||||
'''
|
||||
if 'id' in data:
|
||||
response = json_response()
|
||||
|
|
@ -145,13 +139,14 @@ actions.register(getList)
|
|||
@login_required_json
|
||||
def addListItems(request, data):
|
||||
'''
|
||||
takes {
|
||||
list: listId,
|
||||
items: [itemId],
|
||||
query: ...
|
||||
}
|
||||
returns {
|
||||
}
|
||||
Adds one or more items to a list
|
||||
takes {
|
||||
list: listId,
|
||||
items: [itemId],
|
||||
query: ...
|
||||
}
|
||||
returns {
|
||||
}
|
||||
'''
|
||||
list = get_list_or_404_json(data['list'])
|
||||
if 'items' in data:
|
||||
|
|
@ -174,13 +169,14 @@ actions.register(addListItems, cache=False)
|
|||
@login_required_json
|
||||
def removeListItems(request, data):
|
||||
'''
|
||||
takes {
|
||||
list: listId,
|
||||
items: [itemId],
|
||||
quert: ...
|
||||
}
|
||||
returns {
|
||||
}
|
||||
Removes one or more items from a list
|
||||
takes {
|
||||
list: listId,
|
||||
items: [itemId],
|
||||
quert: ...
|
||||
}
|
||||
returns {
|
||||
}
|
||||
'''
|
||||
list = get_list_or_404_json(data['list'])
|
||||
if 'items' in data:
|
||||
|
|
@ -201,12 +197,14 @@ actions.register(removeListItems, cache=False)
|
|||
@login_required_json
|
||||
def orderListItems(request, data):
|
||||
'''
|
||||
takes {
|
||||
list: string
|
||||
ids: [string]
|
||||
}
|
||||
returns {
|
||||
}
|
||||
Sets the manual order of items in a given list
|
||||
takes {
|
||||
list: string
|
||||
ids: [string]
|
||||
}
|
||||
returns {
|
||||
}
|
||||
notes: There is no UI for this yet.
|
||||
'''
|
||||
list = get_list_or_404_json(data['list'])
|
||||
response = json_response()
|
||||
|
|
@ -225,23 +223,25 @@ actions.register(orderListItems, cache=False)
|
|||
@login_required_json
|
||||
def addList(request, data):
|
||||
'''
|
||||
takes {
|
||||
name: value,
|
||||
}
|
||||
possible keys to create list:
|
||||
name
|
||||
description
|
||||
type
|
||||
query
|
||||
items
|
||||
view
|
||||
sort
|
||||
Adds a new list
|
||||
takes {
|
||||
name: value,
|
||||
}
|
||||
possible keys to create list:
|
||||
name
|
||||
description
|
||||
type
|
||||
query
|
||||
items
|
||||
view
|
||||
sort
|
||||
|
||||
returns {
|
||||
id: string,
|
||||
name: string,
|
||||
...
|
||||
}
|
||||
returns {
|
||||
id: string,
|
||||
name: string,
|
||||
...
|
||||
}
|
||||
see: editList, findLists, getList, removeList, sortLists
|
||||
'''
|
||||
data['name'] = re.sub(' \[\d+\]$', '', data.get('name', 'Untitled')).strip()
|
||||
name = data['name']
|
||||
|
|
@ -285,19 +285,21 @@ actions.register(addList, cache=False)
|
|||
@login_required_json
|
||||
def editList(request, data):
|
||||
'''
|
||||
takes {
|
||||
id: listId,
|
||||
key: value,
|
||||
}
|
||||
keys: name, status, query, position, posterFrames
|
||||
if you change status you have to provide position of list
|
||||
Edits a list
|
||||
takes {
|
||||
id: listId,
|
||||
key: value,
|
||||
}
|
||||
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,
|
||||
...
|
||||
}
|
||||
posterFrames:
|
||||
array with objects that have item/position
|
||||
returns {
|
||||
id: string,
|
||||
...
|
||||
}
|
||||
see: addList, findLists, getList, removeList, sortLists
|
||||
'''
|
||||
list = get_list_or_404_json(data['id'])
|
||||
if list.editable(request.user):
|
||||
|
|
@ -313,11 +315,12 @@ actions.register(editList, cache=False)
|
|||
@login_required_json
|
||||
def removeList(request, data):
|
||||
'''
|
||||
takes {
|
||||
id: listId,
|
||||
}
|
||||
returns {
|
||||
}
|
||||
Removes a list
|
||||
takes {
|
||||
id: string // list id
|
||||
}
|
||||
returns {}
|
||||
see: addList, editList, findLists, getList, sortLists
|
||||
'''
|
||||
list = get_list_or_404_json(data['id'])
|
||||
response = json_response()
|
||||
|
|
@ -334,11 +337,12 @@ actions.register(removeList, cache=False)
|
|||
@login_required_json
|
||||
def subscribeToList(request, data):
|
||||
'''
|
||||
takes {
|
||||
id: listId,
|
||||
}
|
||||
returns {
|
||||
}
|
||||
Adds a list to favorites
|
||||
takes {
|
||||
id: listId,
|
||||
}
|
||||
returns {}
|
||||
see: unsubscribeFromList
|
||||
'''
|
||||
list = get_list_or_404_json(data['id'])
|
||||
user = request.user
|
||||
|
|
@ -359,12 +363,13 @@ actions.register(subscribeToList, cache=False)
|
|||
@login_required_json
|
||||
def unsubscribeFromList(request, data):
|
||||
'''
|
||||
takes {
|
||||
id: listId,
|
||||
user: username(only admins)
|
||||
}
|
||||
returns {
|
||||
}
|
||||
Removes a list from favorites
|
||||
takes {
|
||||
id: listId,
|
||||
user: username(only admins)
|
||||
}
|
||||
returns {}
|
||||
see: subscribeToList
|
||||
'''
|
||||
list = get_list_or_404_json(data['id'])
|
||||
user = request.user
|
||||
|
|
@ -379,14 +384,14 @@ actions.register(unsubscribeFromList, cache=False)
|
|||
@login_required_json
|
||||
def sortLists(request, data):
|
||||
'''
|
||||
takes {
|
||||
section: 'personal',
|
||||
ids: [1,2,4,3]
|
||||
}
|
||||
known sections: 'personal', 'public', 'featured'
|
||||
featured can only be edited by admins
|
||||
returns {
|
||||
}
|
||||
Set order of lists
|
||||
takes {
|
||||
section: 'personal',
|
||||
ids: [1,2,4,3]
|
||||
}
|
||||
known sections: 'personal', 'public', 'featured'
|
||||
featured can only be edited by admins
|
||||
returns {}
|
||||
'''
|
||||
position = 0
|
||||
section = data['section']
|
||||
|
|
|
|||
|
|
@ -20,23 +20,24 @@ import models
|
|||
@login_required_json
|
||||
def addPlace(request, data):
|
||||
'''
|
||||
takes {
|
||||
name: "",
|
||||
alternativeNames: [],
|
||||
geoname: "",
|
||||
countryCode: '',
|
||||
south: float,
|
||||
west: float,
|
||||
north: float,
|
||||
east: float,
|
||||
lat: float,
|
||||
lng: float,
|
||||
area: float,
|
||||
type: ""
|
||||
}
|
||||
returns {
|
||||
id: string
|
||||
}
|
||||
Adds a place
|
||||
takes {
|
||||
name: "",
|
||||
alternativeNames: [],
|
||||
geoname: "",
|
||||
countryCode: '',
|
||||
south: float,
|
||||
west: float,
|
||||
north: float,
|
||||
east: float,
|
||||
lat: float,
|
||||
lng: float,
|
||||
area: float,
|
||||
type: ""
|
||||
}
|
||||
returns {
|
||||
id: string
|
||||
}
|
||||
'''
|
||||
#FIXME: check permissions
|
||||
exists = False
|
||||
|
|
@ -102,14 +103,15 @@ actions.register(addPlace, cache=False)
|
|||
@login_required_json
|
||||
def editPlace(request, data):
|
||||
'''
|
||||
takes {
|
||||
id: string,
|
||||
name: string
|
||||
north: int
|
||||
}
|
||||
returns {
|
||||
names: []
|
||||
}
|
||||
Edits a place
|
||||
takes {
|
||||
id: string,
|
||||
name: string
|
||||
north: int
|
||||
}
|
||||
returns {
|
||||
names: []
|
||||
}
|
||||
'''
|
||||
place = get_object_or_404_json(models.Place, pk=ox.fromAZ(data['id']))
|
||||
names = data.get('name', [])
|
||||
|
|
@ -167,10 +169,12 @@ actions.register(editPlace, cache=False)
|
|||
@login_required_json
|
||||
def removePlace(request, data):
|
||||
'''
|
||||
takes {
|
||||
id: string,
|
||||
}
|
||||
returns {}
|
||||
Removes a place
|
||||
takes {
|
||||
id: string,
|
||||
}
|
||||
returns {}
|
||||
see: addPlace, editPlace, findPlaces
|
||||
'''
|
||||
if isinstance(data, dict):
|
||||
data = data['id']
|
||||
|
|
@ -215,61 +219,61 @@ def order_query(qs, sort):
|
|||
|
||||
def findPlaces(request, data):
|
||||
'''
|
||||
takes {
|
||||
query: {
|
||||
conditions: [
|
||||
{
|
||||
key: 'user',
|
||||
value: 'something',
|
||||
operator: '='
|
||||
}
|
||||
]
|
||||
operator: ","
|
||||
},
|
||||
itemsQuery: {
|
||||
//see find request
|
||||
},
|
||||
sort: [{key: 'name', operator: '+'}],
|
||||
range: [int, int]
|
||||
keys: [string]
|
||||
}
|
||||
takes {
|
||||
query: {
|
||||
conditions: [
|
||||
{
|
||||
key: 'user',
|
||||
value: 'something',
|
||||
operator: '='
|
||||
}
|
||||
]
|
||||
operator: ","
|
||||
},
|
||||
itemsQuery: {
|
||||
//see find request
|
||||
},
|
||||
sort: [{key: 'name', operator: '+'}],
|
||||
range: [int, int]
|
||||
keys: [string]
|
||||
}
|
||||
|
||||
possible query keys:
|
||||
name, geoname, user
|
||||
possible query keys:
|
||||
name, geoname, user
|
||||
|
||||
itemsQuery can be used to limit the resuts to matches in those items.
|
||||
Uses the same query syntax as used in the find request.
|
||||
itemsQuery can be used to limit the resuts to matches in those items.
|
||||
Uses the same query syntax as used in the find request.
|
||||
|
||||
possible keys:
|
||||
name, geoname, user
|
||||
|
||||
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]
|
||||
possible keys:
|
||||
name, geoname, user
|
||||
|
||||
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: [string]
|
||||
}
|
||||
with keys, items is list of dicts with requested properties:
|
||||
returns {
|
||||
items: [string]
|
||||
}
|
||||
|
||||
Positions
|
||||
takes {
|
||||
|
|
@ -316,10 +320,11 @@ actions.register(findPlaces)
|
|||
|
||||
def getPlaceNames(request, data):
|
||||
'''
|
||||
takes {}
|
||||
returns {
|
||||
items: [{name: string, matches: int}]
|
||||
}
|
||||
Undocumented
|
||||
takes {}
|
||||
returns {
|
||||
items: [{name: string, matches: int}]
|
||||
}
|
||||
'''
|
||||
response = json_response({})
|
||||
layers = [l['id'] for l in filter(lambda l: l['type'] == 'place',
|
||||
|
|
|
|||
Loading…
Reference in a new issue