update api docs

This commit is contained in:
rolux 2014-12-18 19:26:37 +00:00
parent 09b9b1d90e
commit 0a56268b92
6 changed files with 299 additions and 277 deletions

View file

@ -45,8 +45,9 @@ def addClips(request, data):
] ]
} }
returns {} returns {}
notes: Clips are either {item, in, out} or {annotation}. If index is notes: Clips are either {item, in, out} (by value) or {annotation} (by
missing, clips will be inserted at the end of the edit. reference). If `index` is missing, clips will be inserted at the end of the
edit.
see: editClip, orderClips, removeClips, sortClips see: editClip, orderClips, removeClips, sortClips
''' '''
response = json_response() response = json_response()

View file

@ -31,14 +31,14 @@ def get_entity_or_404_json(id):
@login_required_json @login_required_json
def addEntity(request, data): def addEntity(request, data):
''' '''
add entity Adds an entity
takes { takes {
type: type: string,
name: name: string,
alternativeNames alternativeNames: [string]
} }
returns { returns {}
} see: editEntity, findEntities, getEntity, removeEntity
''' '''
existing_names = [] existing_names = []
exists = False exists = False
@ -97,6 +97,7 @@ def autocompleteEntities(request, data):
returns { returns {
items: [{id, name,...}, ...] // array of matching entities items: [{id, name,...}, ...] // array of matching entities
} }
see: autocomplete
''' '''
if not 'range' in data: if not 'range' in data:
data['range'] = [0, 10] data['range'] = [0, 10]
@ -144,16 +145,18 @@ actions.register(autocompleteEntities)
@login_required_json @login_required_json
def editEntity(request, data): def editEntity(request, data):
''' '''
takes { Edits an entity
id: string takes {
name: string id: string
description: string name: string
item(optional): edit descriptoin per item description: string
} item(optional): edit descriptoin per item
returns { }
id: returns {
... id:
} ...
}
see: addEntity, findEntities, getEntity, removeEntity
''' '''
response = json_response() response = json_response()
entity = get_entity_or_404_json(data['id']) entity = get_entity_or_404_json(data['id'])
@ -197,32 +200,25 @@ def parse_query(data, user):
def findEntities(request, data): def findEntities(request, data):
''' '''
takes { Finds entities for a given query
query: { takes {
conditions: [ query: object, // query object, see `find`
{ sort: [object], // list of sort objects, see `find`
key: 'name', range: [int, int], // range of results
value: 'something', keys: [string] // list of properties to return
operator: '=' }
}
]
operator: ","
},
sort: [{key: 'name', operator: '+'}],
range: [0, 100]
keys: []
}
possible query keys: possible query keys:
name, type name, type
possible keys: possible keys:
name, type, alternativeNames name, type, alternativeNames
} }
returns { returns {
items: [object] items: [object]
} }
see: addEntity, editEntity, getEntity, removeEntity
''' '''
query = parse_query(data, request.user) query = parse_query(data, request.user)
@ -246,13 +242,15 @@ actions.register(findEntities)
def getEntity(request, data): def getEntity(request, data):
''' '''
takes { Gets an entity by id
id: string, takes {
keys: [string] id: string,
} keys: [string]
returns { }
key: value returns {
} key: value
}
see: addEntity, editEntity, findEntities, removeEntity
''' '''
response = json_response({}) response = json_response({})
data['keys'] = data.get('keys', []) data['keys'] = data.get('keys', [])
@ -264,13 +262,15 @@ actions.register(getEntity)
@login_required_json @login_required_json
def removeEntity(request, data): def removeEntity(request, data):
''' '''
takes { Removes an entity
id: string, takes {
or id: string,
ids: [string] or
} ids: [string]
returns { }
} returns {
}
see: addEntity, editEntity, findEntities, getEntity
''' '''
response = json_response() response = json_response()

View file

@ -19,14 +19,16 @@ import models
@login_required_json @login_required_json
def addEvent(request, data): def addEvent(request, data):
''' '''
takes { Adds a calendar event
name: string, takes {
start: string, name: string,
end: string start: string,
} end: string
returns { }
id: string returns {
} id: string
}
see: editEvent, findEvents, removeEvents
''' '''
existing_names = [] existing_names = []
exists = False exists = False
@ -69,16 +71,18 @@ actions.register(addEvent, cache=False)
@login_required_json @login_required_json
def editEvent(request, data): def editEvent(request, data):
''' '''
takes { Edits a calendar event
id: string, takes {
name: string, id: string,
start: string, name: string,
end: string start: string,
} end: string
returns { }
id: string, returns {
... id: string,
} ...
}
see: addEvent, findEvents, removeEvent
''' '''
event = get_object_or_404_json(models.Event, pk=ox.fromAZ(data['id'])) event = get_object_or_404_json(models.Event, pk=ox.fromAZ(data['id']))
if event.editable(request.user): if event.editable(request.user):
@ -123,11 +127,12 @@ actions.register(editEvent, cache=False)
@login_required_json @login_required_json
def removeEvent(request, data): def removeEvent(request, data):
''' '''
remove Event with given id Removes a calendar event
takes { takes {
id: event id id: event id
} }
returns {} returns {}
see: addEvent, editEvent, findEvents
''' '''
event = get_object_or_404_json(models.Event, pk=ox.fromAZ(data['id'])) event = get_object_or_404_json(models.Event, pk=ox.fromAZ(data['id']))
if event.editable(request.user): if event.editable(request.user):
@ -169,11 +174,12 @@ def order_query(qs, sort):
def findEvents(request, data): def findEvents(request, data):
''' '''
takes { Finds calendar events
query: object, takes {
sort: array query: object,
range': [int, int] sort: array
} range': [int, int]
}
query: query object, more on query syntax at query: query object, more on query syntax at
https://wiki.0x2620.org/wiki/pandora/QuerySyntax https://wiki.0x2620.org/wiki/pandora/QuerySyntax
@ -238,11 +244,12 @@ actions.register(findEvents)
def getEventNames(request, data): def getEventNames(request, data):
''' '''
takes { Undocumented
} takes {
returns { }
items: [{name: string, matches: int}] returns {
} items: [{name: string, matches: int}]
}
''' '''
response = json_response({}) response = json_response({})
layers = [l['id'] for l in filter(lambda l: l['type'] == 'event', layers = [l['id'] for l in filter(lambda l: l['type'] == 'event',

View file

@ -160,6 +160,10 @@ def find(request, data):
notes: Comparison operators are '=' (contains) '==' (is), '^' (starts with), notes: Comparison operators are '=' (contains) '==' (is), '^' (starts with),
'$' (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
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 see: add, edit, get, lookup, remove, upload
''' '''
if settings.JSON_DEBUG: if settings.JSON_DEBUG:

View file

@ -58,32 +58,24 @@ def parse_query(data, user):
def findLists(request, data): def findLists(request, data):
''' '''
takes { takes {
query: { query: object, // query object, see `find`
conditions: [ sort: [], // list of sort objects, see `find`
{ range: [int, int], // range of results
key: 'user', keys: [string] // properties to return
value: 'something', }
operator: '='
}
]
operator: ","
},
sort: [{key: 'name', operator: '+'}],
range: [0, 100]
keys: []
}
possible query keys: possible query keys:
name, user, featured, subscribed name, user, featured, subscribed
possible keys: possible keys:
name, user, featured, subscribed, query name, user, featured, subscribed, query
} }
returns { returns {
items: [{name: string, user: string, featured: bool, public...}] items: [{name: string, user: string, featured: bool, public...}]
} }
see: addList, editList, getList, removeList, sortLists
''' '''
query = parse_query(data, request.user) query = parse_query(data, request.user)
@ -121,14 +113,16 @@ actions.register(findLists)
def getList(request, data): def getList(request, data):
''' '''
takes { Gets a list by id
id: listid takes {
} id: listid
returns { }
id: returns {
section: id:
... section:
} ...
}
see: addList, editList, findLists, removeList, sortLists
''' '''
if 'id' in data: if 'id' in data:
response = json_response() response = json_response()
@ -145,13 +139,14 @@ actions.register(getList)
@login_required_json @login_required_json
def addListItems(request, data): def addListItems(request, data):
''' '''
takes { Adds one or more items to a list
list: listId, takes {
items: [itemId], list: listId,
query: ... items: [itemId],
} query: ...
returns { }
} returns {
}
''' '''
list = get_list_or_404_json(data['list']) list = get_list_or_404_json(data['list'])
if 'items' in data: if 'items' in data:
@ -174,13 +169,14 @@ actions.register(addListItems, cache=False)
@login_required_json @login_required_json
def removeListItems(request, data): def removeListItems(request, data):
''' '''
takes { Removes one or more items from a list
list: listId, takes {
items: [itemId], list: listId,
quert: ... items: [itemId],
} quert: ...
returns { }
} returns {
}
''' '''
list = get_list_or_404_json(data['list']) list = get_list_or_404_json(data['list'])
if 'items' in data: if 'items' in data:
@ -201,12 +197,14 @@ actions.register(removeListItems, cache=False)
@login_required_json @login_required_json
def orderListItems(request, data): def orderListItems(request, data):
''' '''
takes { Sets the manual order of items in a given list
list: string takes {
ids: [string] list: string
} ids: [string]
returns { }
} returns {
}
notes: There is no UI for this yet.
''' '''
list = get_list_or_404_json(data['list']) list = get_list_or_404_json(data['list'])
response = json_response() response = json_response()
@ -225,23 +223,25 @@ actions.register(orderListItems, cache=False)
@login_required_json @login_required_json
def addList(request, data): def addList(request, data):
''' '''
takes { Adds a new list
name: value, takes {
} name: value,
possible keys to create list: }
name possible keys to create list:
description name
type description
query type
items query
view items
sort view
sort
returns { returns {
id: string, id: string,
name: string, name: string,
... ...
} }
see: editList, findLists, getList, removeList, sortLists
''' '''
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']
@ -285,19 +285,21 @@ actions.register(addList, cache=False)
@login_required_json @login_required_json
def editList(request, data): def editList(request, data):
''' '''
takes { Edits a list
id: listId, takes {
key: value, id: listId,
} key: value,
keys: name, status, query, position, posterFrames }
if you change status you have to provide position of list keys: name, status, query, position, posterFrames
if you change status you have to provide position of list
posterFrames: posterFrames:
array with objects that have item/position array with objects that have item/position
returns { returns {
id: string, id: string,
... ...
} }
see: addList, findLists, getList, removeList, sortLists
''' '''
list = get_list_or_404_json(data['id']) list = get_list_or_404_json(data['id'])
if list.editable(request.user): if list.editable(request.user):
@ -313,11 +315,12 @@ actions.register(editList, cache=False)
@login_required_json @login_required_json
def removeList(request, data): def removeList(request, data):
''' '''
takes { Removes a list
id: listId, takes {
} id: string // list id
returns { }
} returns {}
see: addList, editList, findLists, getList, sortLists
''' '''
list = get_list_or_404_json(data['id']) list = get_list_or_404_json(data['id'])
response = json_response() response = json_response()
@ -334,11 +337,12 @@ actions.register(removeList, cache=False)
@login_required_json @login_required_json
def subscribeToList(request, data): def subscribeToList(request, data):
''' '''
takes { Adds a list to favorites
id: listId, takes {
} id: listId,
returns { }
} returns {}
see: unsubscribeFromList
''' '''
list = get_list_or_404_json(data['id']) list = get_list_or_404_json(data['id'])
user = request.user user = request.user
@ -359,12 +363,13 @@ actions.register(subscribeToList, cache=False)
@login_required_json @login_required_json
def unsubscribeFromList(request, data): def unsubscribeFromList(request, data):
''' '''
takes { Removes a list from favorites
id: listId, takes {
user: username(only admins) id: listId,
} user: username(only admins)
returns { }
} returns {}
see: subscribeToList
''' '''
list = get_list_or_404_json(data['id']) list = get_list_or_404_json(data['id'])
user = request.user user = request.user
@ -379,14 +384,14 @@ actions.register(unsubscribeFromList, cache=False)
@login_required_json @login_required_json
def sortLists(request, data): def sortLists(request, data):
''' '''
takes { Set order of lists
section: 'personal', takes {
ids: [1,2,4,3] section: 'personal',
} ids: [1,2,4,3]
known sections: 'personal', 'public', 'featured' }
featured can only be edited by admins known sections: 'personal', 'public', 'featured'
returns { featured can only be edited by admins
} returns {}
''' '''
position = 0 position = 0
section = data['section'] section = data['section']

View file

@ -20,23 +20,24 @@ import models
@login_required_json @login_required_json
def addPlace(request, data): def addPlace(request, data):
''' '''
takes { Adds a place
name: "", takes {
alternativeNames: [], name: "",
geoname: "", alternativeNames: [],
countryCode: '', geoname: "",
south: float, countryCode: '',
west: float, south: float,
north: float, west: float,
east: float, north: float,
lat: float, east: float,
lng: float, lat: float,
area: float, lng: float,
type: "" area: float,
} type: ""
returns { }
id: string returns {
} id: string
}
''' '''
#FIXME: check permissions #FIXME: check permissions
exists = False exists = False
@ -102,14 +103,15 @@ actions.register(addPlace, cache=False)
@login_required_json @login_required_json
def editPlace(request, data): def editPlace(request, data):
''' '''
takes { Edits a place
id: string, takes {
name: string id: string,
north: int name: string
} north: int
returns { }
names: [] returns {
} names: []
}
''' '''
place = get_object_or_404_json(models.Place, pk=ox.fromAZ(data['id'])) place = get_object_or_404_json(models.Place, pk=ox.fromAZ(data['id']))
names = data.get('name', []) names = data.get('name', [])
@ -167,10 +169,12 @@ actions.register(editPlace, cache=False)
@login_required_json @login_required_json
def removePlace(request, data): def removePlace(request, data):
''' '''
takes { Removes a place
id: string, takes {
} id: string,
returns {} }
returns {}
see: addPlace, editPlace, findPlaces
''' '''
if isinstance(data, dict): if isinstance(data, dict):
data = data['id'] data = data['id']
@ -215,61 +219,61 @@ def order_query(qs, sort):
def findPlaces(request, data): def findPlaces(request, data):
''' '''
takes { takes {
query: { query: {
conditions: [ conditions: [
{ {
key: 'user', key: 'user',
value: 'something', value: 'something',
operator: '=' operator: '='
} }
] ]
operator: "," operator: ","
}, },
itemsQuery: { itemsQuery: {
//see find request //see find request
}, },
sort: [{key: 'name', operator: '+'}], sort: [{key: 'name', operator: '+'}],
range: [int, int] range: [int, int]
keys: [string] keys: [string]
} }
possible query keys: possible query keys:
name, geoname, user name, geoname, user
itemsQuery can be used to limit the resuts to matches in those items. itemsQuery can be used to limit the resuts to matches in those items.
Uses the same query syntax as used in the find request. Uses the same query syntax as used in the find request.
possible keys: possible keys:
name, geoname, user name, geoname, user
returns { returns {
items: [object] items: [object]
} }
takes { takes {
query: object, query: object,
sort: [object] sort: [object]
range: [int, int] range: [int, int]
} }
query: query object, more on query syntax at query: query object, more on query syntax at
https://wiki.0x2620.org/wiki/pandora/QuerySyntax https://wiki.0x2620.org/wiki/pandora/QuerySyntax
sort: array of key, operator dics sort: array of key, operator dics
[ [
{ {
key: "year", key: "year",
operator: "-" operator: "-"
}, },
{ {
key: "director", key: "director",
operator: "" operator: ""
} }
] ]
range: result range, array [from, to] range: result range, array [from, to]
with keys, items is list of dicts with requested properties: with keys, items is list of dicts with requested properties:
returns { returns {
items: [string] items: [string]
} }
Positions Positions
takes { takes {
@ -316,10 +320,11 @@ actions.register(findPlaces)
def getPlaceNames(request, data): def getPlaceNames(request, data):
''' '''
takes {} Undocumented
returns { takes {}
items: [{name: string, matches: int}] returns {
} items: [{name: string, matches: int}]
}
''' '''
response = json_response({}) response = json_response({})
layers = [l['id'] for l in filter(lambda l: l['type'] == 'place', layers = [l['id'] for l in filter(lambda l: l['type'] == 'place',