0x2620/pandora
2
1
Fork 1
Code Issues 1.3k Pull requests Releases Wiki Activity

update api docs

Browse source
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
Show stats Download patch file Download diff file Expand all files Collapse all files

4
pandora/archive/views.py
View file

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

4
pandora/document/views.py
View file

@ -72,8 +72,8 @@ def editDocument(request, data):
item: string // item id (optional)
}
returns {
id:
...
id: string, // document id
... // more document properties
}
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

9
pandora/edit/views.py
View file

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

19
pandora/entity/views.py
View file

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

20
pandora/event/views.py
View file

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

3
pandora/item/views.py
View file

@ -164,6 +164,7 @@ def find(request, data):
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.
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
'''
if settings.JSON_DEBUG:
@ -500,7 +501,7 @@ def add(request, data):
title: string, // title
... // 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
'''
if not request.user.get_profile().capability('canAddItems'):

4
pandora/itemlist/views.py
View file

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

120
pandora/place/views.py
View file

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

71
pandora/user/views.py
View file

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