update api docs

This commit is contained in:
rolux 2014-12-19 12:59:10 +00:00
parent 1ddc23b9f3
commit 4a084d8405
9 changed files with 112 additions and 142 deletions

View file

@ -161,8 +161,8 @@ def addMedia(request, data):
''' '''
Adds media files to a given item Adds media files to a given item
takes { takes {
filename: string, // undocumented filename: string, // filename
id: oshash, // undocumented id: string, // oshash of the file
info: {}, // undocumented info: {}, // undocumented
item: string // item id item: string // item id
} }

View file

@ -72,8 +72,8 @@ def editDocument(request, data):
item: string // item id (optional) item: string // item id (optional)
} }
returns { returns {
id: id: string, // document id
... ... // more document properties
} }
notes: If `item` is present, this will not edit the global description of notes: If `item` is present, this will not edit the global description of
the document, but its specific description in the context of the given the document, but its specific description in the context of the given

View file

@ -28,7 +28,7 @@ def get_edit_or_404_json(id):
@login_required_json @login_required_json
def addClips(request, data): def addClips(request, data):
''' '''
Adds one or more clips to an edit Adds one or more clips to a static edit
takes { takes {
edit: string, // edit id, edit: string, // edit id,
index: int, // position within edit (optional), index: int, // position within edit (optional),
@ -75,7 +75,7 @@ actions.register(addClips, cache=False)
@login_required_json @login_required_json
def removeClips(request, data): def removeClips(request, data):
''' '''
Removes one or more clips from an edit Removes one or more clips from a static edit
takes { takes {
edit: string, // edit id edit: string, // edit id
ids: [string] // clip ids ids: [string] // clip ids
@ -109,8 +109,7 @@ def editClip(request, data):
in: float, // in point in seconds in: float, // in point in seconds
out: float // out point in seconds out: float // out point in seconds
} }
returns { returns {}
}
see: addClips, orderClips, removeClips, sortClips see: addClips, orderClips, removeClips, sortClips
''' '''
response = json_response() response = json_response()
@ -245,7 +244,7 @@ actions.register(getEdit)
@login_required_json @login_required_json
def addEdit(request, data): def addEdit(request, data):
''' '''
Adds an edit Adds a new edit
takes { takes {
name: string, // name (optional) name: string, // name (optional)
type: string // 'static' or 'smart' type: string // 'static' or 'smart'

View file

@ -33,9 +33,10 @@ def addEntity(request, data):
''' '''
Adds an entity Adds an entity
takes { takes {
type: string, type: string, // entity type, as defined in config
name: string, name: string, // name
alternativeNames: [string] alternativeNames: [string], // list of alternative names
... // more entity properties, as defined in config
} }
returns {} returns {}
see: editEntity, findEntities, getEntity, removeEntity see: editEntity, findEntities, getEntity, removeEntity
@ -148,14 +149,14 @@ def editEntity(request, data):
''' '''
Edits an entity Edits an entity
takes { takes {
id: string id: string, // entity id
name: string name: string, // entity name
description: string description: string, // entity description
item(optional): edit descriptoin per item ... // more properties, as defined in config
} }
returns { returns {
id: id: string // entity id
... ... // more entity properties
} }
see: addEntity, findEntities, getEntity, removeEntity see: addEntity, findEntities, getEntity, removeEntity
''' '''

View file

@ -19,7 +19,7 @@ import models
@login_required_json @login_required_json
def addEvent(request, data): def addEvent(request, data):
''' '''
Adds a new calendar event Adds a new event to the calendar
takes { takes {
end: string, // 'YYYY-MM-DD HH:MM:SS', arbitrary precision end: string, // 'YYYY-MM-DD HH:MM:SS', arbitrary precision
name: string, // name name: string, // name
@ -128,7 +128,7 @@ actions.register(editEvent, cache=False)
@login_required_json @login_required_json
def removeEvent(request, data): def removeEvent(request, data):
''' '''
Removes a calendar event Removes an event from the calendar
takes { takes {
id: string // event id id: string // event id
} }
@ -175,7 +175,7 @@ def order_query(qs, sort):
def findEvents(request, data): def findEvents(request, data):
''' '''
Finds calendar events Finds calendar events 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`
@ -216,12 +216,18 @@ actions.register(findEvents)
def getEventNames(request, data): def getEventNames(request, data):
''' '''
Undocumented Gets event names and matches
takes { takes {}
}
returns { returns {
items: [{name: string, matches: int}] items: [
{
name: string, // event name
matches: int // number of matches in annotations
},
... // more events
]
} }
see: getPlaceNames
''' '''
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

@ -164,6 +164,7 @@ def find(request, data):
responsive GUI: First leave out `keys` to get totals as fast as possible, responsive GUI: 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>.
see: add, edit, get, lookup, remove, upload see: add, edit, get, lookup, remove, upload
''' '''
if settings.JSON_DEBUG: if settings.JSON_DEBUG:
@ -500,7 +501,7 @@ def add(request, data):
title: string, // title title: string, // title
... // more item properties ... // more item properties
} }
notes: To allow for this, set config option `itemRequiresVideo` to false notes: To allow for this, set config option `itemRequiresVideo` to false.
see: edit, find, get, lookup, remove, upload see: edit, find, get, lookup, remove, upload
''' '''
if not request.user.get_profile().capability('canAddItems'): if not request.user.get_profile().capability('canAddItems'):

View file

@ -139,7 +139,7 @@ actions.register(getList)
@login_required_json @login_required_json
def addListItems(request, data): def addListItems(request, data):
''' '''
Adds one or more items to a list Adds one or more items to a static list
takes { takes {
list: string, // list id list: string, // list id
items: [string], // either list of item ids items: [string], // either list of item ids
@ -169,7 +169,7 @@ actions.register(addListItems, cache=False)
@login_required_json @login_required_json
def removeListItems(request, data): def removeListItems(request, data):
''' '''
Removes one or more items from a list Removes one or more items from a static list
takes { takes {
list: string, // list id list: string, // list id
items: [itemId], // either list of item ids items: [itemId], // either list of item ids

View file

@ -20,24 +20,24 @@ import models
@login_required_json @login_required_json
def addPlace(request, data): def addPlace(request, data):
''' '''
Adds a new place Adds a new place to the map
takes { takes {
name: "", name: string, // place name
alternativeNames: [], alternativeNames: [string], // list of alternative names
geoname: "", geoname: string, // full geoname (like '23 Main St, Foo, Switzerland')
countryCode: '', countryCode: string, // two-letter country code (like 'ch')
south: float, south: float, // southern edge of the bounding box in degrees
west: float, west: float, // western edge of the bounding box in degrees
north: float, north: float, // northern edge of the bounding box in degrees
east: float, east: float, // eastern edge of the bounding box in degrees
lat: float, type: string // place type
lng: float,
area: float,
type: ""
} }
returns { returns {
id: string id: string
} }
notes: Possible types are 'country', 'region', 'city', 'borough', 'street',
'building' and 'feature'.
see: editPlace, findPlaces, removePlace
''' '''
#FIXME: check permissions #FIXME: check permissions
exists = False exists = False
@ -105,13 +105,14 @@ def editPlace(request, data):
''' '''
Edits a place Edits a place
takes { takes {
id: string, id: string, // place id
name: string name: string, // place name
north: int ... // more place properties
} }
returns { returns {
names: [] names: [] // list of names, in case of collision with existing data
} }
see: addPlace, findPlaces, removePlace
''' '''
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', [])
@ -169,9 +170,9 @@ actions.register(editPlace, cache=False)
@login_required_json @login_required_json
def removePlace(request, data): def removePlace(request, data):
''' '''
Removes a place Removes a place from the map
takes { takes {
id: string, id: string // place id
} }
returns {} returns {}
see: addPlace, editPlace, findPlaces see: addPlace, editPlace, findPlaces
@ -219,70 +220,20 @@ def order_query(qs, sort):
def findPlaces(request, data): def findPlaces(request, data):
''' '''
Finds places for a given query
takes { takes {
query: { query: object, // query object to find places, see `find`
conditions: [ itemsQuery: object // query object to limit results to items, 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: '='
}
]
operator: ","
},
itemsQuery: {
//see find request
},
sort: [{key: 'name', operator: '+'}],
range: [int, int]
keys: [string]
} }
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.
possible keys:
name, geoname, user
returns { returns {
items: [object] items: [object] // list of place objects
} }
takes { notes: Possible query keys are 'geoname', 'name' and 'user'. Possible
query: object, itemsQuery keys are all item keys, as defined in the config.
sort: [object] see: addPlace, editPlace, removePlace
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]
}
Positions
takes {
query: object,
positions: [string]
}
query: query object, more on query syntax at
https://wiki.0x2620.org/wiki/pandora/QuerySyntax
positions: ids of places for which positions are required
''' '''
response = json_response() response = json_response()
@ -320,11 +271,18 @@ actions.register(findPlaces)
def getPlaceNames(request, data): def getPlaceNames(request, data):
''' '''
Undocumented Gets place names and matches
takes {} takes {}
returns { returns {
items: [{name: string, matches: int}] items: [
{
name: string, // place name
matches: int // number of matches in annotations
},
... // more places
]
} }
see: getEventNames
''' '''
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',

View file

@ -669,12 +669,12 @@ def contact(request, data):
''' '''
Sends a message to the contact address Sends a message to the contact address
takes { takes {
email: string, email: string, // sender
subject: string, subject: string, // subject
message: string message: string // message
}
returns {
} }
returns {}
see: mail
''' '''
name = data.get('name', '') name = data.get('name', '')
email = data.get('email', '') email = data.get('email', '')
@ -856,7 +856,7 @@ def statistics(request, data):
Gets usage statistics Gets usage statistics
takes {} takes {}
returns { returns {
... // undocumented ... // various statistics
} }
''' '''
response = json_response() response = json_response()
@ -883,14 +883,20 @@ def group_json(g):
@login_required_json @login_required_json
def getGroups(request, data): def getGroups(request, data):
''' '''
Gets user groups Gets all user groups
takes {} takes {}
returns { returns {
groups: [ groups: [
{id: string, name: string, users: int, items: int} {
id: string, // group id
name: string, // group name
users: int, // number of users in this group
items: int // number of items in this groups
},
... // more groups
] ]
} }
see: addGroup, editGroup, getGroups, removeGroup see: addGroup, editGroup, getGroup, removeGroup
''' '''
response = json_response(status=200, text='ok') response = json_response(status=200, text='ok')
response['data']['groups'] = [] response['data']['groups'] = []
@ -903,17 +909,16 @@ actions.register(getGroups)
@login_required_json @login_required_json
def getGroup(request, data): def getGroup(request, data):
''' '''
Gets user group Gets a user group by id or name
takes { takes {
id: string id: string // either group id
or name: string // or group name
name: string
} }
returns { returns {
id: string, id: string, // group id
name: string name: string, // group name
users: int users: int, // number of users in this group
items: int items: int // number of items in this group
} }
see: addGroup, editGroup, getGroups, removeGroup see: addGroup, editGroup, getGroups, removeGroup
''' '''
@ -927,15 +932,15 @@ actions.register(getGroup, cache=False)
@capability_required_json('canManageUsers') @capability_required_json('canManageUsers')
def addGroup(request, data): def addGroup(request, data):
''' '''
Adds user group Adds a new user group
takes { takes {
name: string name: string // group name
} }
returns { returns {
id: string, id: string, // group id
name: string name: string, // group name
users: int users: int, // number of users in this group
items: int items: int // number of items in this group
} }
see: editGroup, getGroup, getGroups, removeGroup see: editGroup, getGroup, getGroups, removeGroup
''' '''
@ -957,15 +962,16 @@ actions.register(addGroup, cache=False)
@capability_required_json('canManageUsers') @capability_required_json('canManageUsers')
def editGroup(request, data): def editGroup(request, data):
''' '''
Edits user group Edits a user group
takes { takes {
id: string, id: string, // group id
name: string name: string // group name
} }
returns { returns {
name: string id: string, // group id
users: int name: string, // group name
users: int, // number of users in this group
items: int // number of items in this group
} }
see: addGroup, getGroup, getGroups, removeGroup see: addGroup, getGroup, getGroups, removeGroup
''' '''
@ -982,12 +988,11 @@ actions.register(editGroup, cache=False)
@capability_required_json('canManageUsers') @capability_required_json('canManageUsers')
def removeGroup(request, data): def removeGroup(request, data):
''' '''
Removes user group Removes a user group
takes { takes {
id: string id: string // group id
}
returns {
} }
returns {}
see: addGroup, editGroup, getGroup, getGroups see: addGroup, editGroup, getGroup, getGroups
''' '''
response = json_response(status=200, text='ok') response = json_response(status=200, text='ok')