From 4a084d8405a867d8e28f6ade5d2664f75c930c54 Mon Sep 17 00:00:00 2001 From: rolux Date: Fri, 19 Dec 2014 12:59:10 +0000 Subject: [PATCH] update api docs --- pandora/archive/views.py | 4 +- pandora/document/views.py | 4 +- pandora/edit/views.py | 9 ++- pandora/entity/views.py | 19 +++--- pandora/event/views.py | 20 ++++--- pandora/item/views.py | 3 +- pandora/itemlist/views.py | 4 +- pandora/place/views.py | 120 +++++++++++++------------------------- pandora/user/views.py | 71 +++++++++++----------- 9 files changed, 112 insertions(+), 142 deletions(-) diff --git a/pandora/archive/views.py b/pandora/archive/views.py index 0baaf397d..fd4c1465d 100644 --- a/pandora/archive/views.py +++ b/pandora/archive/views.py @@ -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 } diff --git a/pandora/document/views.py b/pandora/document/views.py index 52552c085..fd6a39f33 100644 --- a/pandora/document/views.py +++ b/pandora/document/views.py @@ -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 diff --git a/pandora/edit/views.py b/pandora/edit/views.py index a506d4332..e1feafa87 100644 --- a/pandora/edit/views.py +++ b/pandora/edit/views.py @@ -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' diff --git a/pandora/entity/views.py b/pandora/entity/views.py index 44369f035..8351e3b9a 100644 --- a/pandora/entity/views.py +++ b/pandora/entity/views.py @@ -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 ''' diff --git a/pandora/event/views.py b/pandora/event/views.py index 86bcf5779..af9a07c57 100644 --- a/pandora/event/views.py +++ b/pandora/event/views.py @@ -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', diff --git a/pandora/item/views.py b/pandora/item/views.py index 95b6cea46..69b4827e1 100644 --- a/pandora/item/views.py +++ b/pandora/item/views.py @@ -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 0x2620.org wiki. 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'): diff --git a/pandora/itemlist/views.py b/pandora/itemlist/views.py index e0a3e38eb..3171e6bb5 100644 --- a/pandora/itemlist/views.py +++ b/pandora/itemlist/views.py @@ -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 diff --git a/pandora/place/views.py b/pandora/place/views.py index 3bf4aa3f1..3b34b3602 100644 --- a/pandora/place/views.py +++ b/pandora/place/views.py @@ -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: '=' - } - ] - operator: "," - }, - itemsQuery: { - //see find request - }, - sort: [{key: 'name', operator: '+'}], - range: [int, int] - keys: [string] + 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 } - - 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', diff --git a/pandora/user/views.py b/pandora/user/views.py index ad663436a..b7442bd6c 100644 --- a/pandora/user/views.py +++ b/pandora/user/views.py @@ -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')