From cada20f9040e77759a6c3cf028f675c857b2477c Mon Sep 17 00:00:00 2001 From: rolux Date: Fri, 19 Dec 2014 15:05:08 +0000 Subject: [PATCH] update api docs --- pandora/annotation/views.py | 2 +- pandora/app/views.py | 80 +++++++++++++++------------- pandora/archive/views.py | 6 +-- pandora/changelog/views.py | 30 ++++------- pandora/clip/views.py | 32 +++++------ pandora/document/views.py | 2 + pandora/edit/views.py | 33 +++++------- pandora/entity/views.py | 12 ++--- pandora/event/views.py | 2 +- pandora/item/views.py | 4 +- pandora/itemlist/views.py | 19 +++---- pandora/log/views.py | 55 +++++++++---------- pandora/news/views.py | 4 +- pandora/person/views.py | 102 +++++++++++++----------------------- pandora/title/views.py | 85 +++++++++--------------------- 15 files changed, 186 insertions(+), 282 deletions(-) diff --git a/pandora/annotation/views.py b/pandora/annotation/views.py index b96c411a4..dc16ce32f 100644 --- a/pandora/annotation/views.py +++ b/pandora/annotation/views.py @@ -90,7 +90,7 @@ def findAnnotations(request, data): ... // more annotation properties }] } - see: addAnnotation, addAnnotations, editAnnotation, getAnnotation, + see: addAnnotation, addAnnotations, editAnnotation, find, getAnnotation, removeAnnotation ''' response = json_response() diff --git a/pandora/app/views.py b/pandora/app/views.py index b9fe4638a..963d76677 100644 --- a/pandora/app/views.py +++ b/pandora/app/views.py @@ -96,13 +96,15 @@ def robots_txt(request, url): def getPage(request, data): ''' - takes { - name: pagename - } - returns { - name: - text: - } + Gets the text/html for a given site page (like 'About') + takes { + name: string // page id + } + returns { + name: string, // page id + text: string // text/html + } + see: editPage ''' if isinstance(data, basestring): name = data @@ -120,14 +122,16 @@ actions.register(getPage) @login_required_json def editPage(request, data): ''' - takes { - name: pagename - text: text - } - returns { - name: - text: - } + Edits a site page (like 'About') + takes { + name: string, // page id + text: string // new text/html + } + returns { + name: string, // page id + text: string // new text/html + } + see: getPage ''' if request.user.get_profile().capability('canEditSitePages'): page, created = models.Page.objects.get_or_create(name=data['name']) @@ -143,10 +147,12 @@ actions.register(editPage) def init(request, data): ''' - takes {} - returns { - user: object - } + Makes an init request + takes {} + returns { + site: object, // site data + user: object // user data + } ''' response = json_response({}) config = copy.deepcopy(settings.CONFIG) @@ -162,16 +168,16 @@ actions.register(init) def embedURL(request, data): ''' - - takes { - url - maxwidth - maxheight - } - returns { - html - ... - } + Returns HTML to embed a given URL + takes { + url: string, // URL + maxwidth: int, // max width in px + maxheight: int // max height in px + } + returns { + html: string // HTML + } + see: getEmbedDefaults ''' response = json_response({}) response['data'] = ox.get_embed_code(data['url'], data.get('maxwidth'), data.get('maxheight')) @@ -180,19 +186,21 @@ actions.register(embedURL) def getEmbedDefaults(request, data): ''' - takes {} + Returns embed default values + takes {} returns { - document: str // first document, sorted by id - edit: str // first edit, sorted by name - editDuration: float // duration of that edit - item: str // first item, sorted by id + document: string, // first document, sorted by id + edit: string, // first edit, sorted by name + editDuration: float, // duration of that edit + item: string, // first item, sorted by id itemDuration: float // duration of that item itemRatio: float // video ratio of that item - list: str // first list, sorted by name - text: str // first text, sorted by name + list: string // first list, sorted by name + text: string // first text, sorted by name videoRatio: float // pandora.site.video.previewRatio videoResolution: int // largest value in pandora.site.video.resolutions } + see: embedURL ''' from document.models import Document from item.models import Item diff --git a/pandora/archive/views.py b/pandora/archive/views.py index fd4c1465d..f0b5589c6 100644 --- a/pandora/archive/views.py +++ b/pandora/archive/views.py @@ -169,7 +169,7 @@ def addMedia(request, data): returns { item: id // item id } - see: editMedia, moveMedia, removeMedia + see: editMedia, findMedia, moveMedia, removeMedia ''' response = json_response({}) oshash = data.pop('id') @@ -399,7 +399,7 @@ actions.register(moveMedia, cache=False) @login_required_json def editMedia(request, data): ''' - Edits one or more media files + Edits data for one or more media files takes { files: [ { @@ -550,7 +550,7 @@ def findMedia(request, data): returns { items: [object] // list of items } - see: addMedia, editMedia, moveMedia, removeMedia + see: addMedia, editMedia, find, moveMedia, removeMedia ''' if not data.get('sort'): data['sort'] = [{'key': 'path', 'operator': '+'}] diff --git a/pandora/changelog/views.py b/pandora/changelog/views.py index 606d96bde..e853272ad 100644 --- a/pandora/changelog/views.py +++ b/pandora/changelog/views.py @@ -42,25 +42,17 @@ def order_query(qs, sort): @capability_required_json('canManageUsers') def findChangeLogs(request, data): ''' - takes { - query: { - conditions: [ - { - key: 'user', - value: 'something', - operator: '=' - } - ] - operator: "," - }, - sort: [{key: 'created', operator: '+'}], - range: [int, int] - keys: [string] - } - returns { - items: [object] - } - + Finds changelog entries 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 to return + keys: [string] // list of properties to return + } + returns { + items: [object] // list of changelog entries + } + see: find ''' response = json_response() diff --git a/pandora/clip/views.py b/pandora/clip/views.py index 48f889448..c9f17b091 100644 --- a/pandora/clip/views.py +++ b/pandora/clip/views.py @@ -74,25 +74,19 @@ def order_query(qs, sort): def findClips(request, data): ''' - takes { - query: { - conditions: [object], - operator: string // '&' or '|' - }, - itemsQuery: { - conditions: [], - operator: string // '&' or '|' - }, - keys: [string], - position: int, - positions: [string], - range: [int, int], - sort: [] - } - - returns { - items: [object] - } + Finds clips for a given query + takes { + query: object, // find clips, query object, see `find` + itemsQuery: object, // limit to matching items, query object, see `find` + keys: [string], // list of properties to return + positions: [int], // list of positions + range: [int, int], // range of results to return + sort: [object] // list of sort objects, see `find` + } + returns { + items: [object] // list of clip objects + } + see: find ''' response = json_response() diff --git a/pandora/document/views.py b/pandora/document/views.py index fd6a39f33..b629b57e3 100644 --- a/pandora/document/views.py +++ b/pandora/document/views.py @@ -65,6 +65,7 @@ actions.register(addDocument, cache=False) @login_required_json def editDocument(request, data): ''' + Edits data for a document takes { id: string, // document id name: string, // new document name @@ -141,6 +142,7 @@ def parse_query(data, user): def findDocuments(request, data): ''' + Finds documents for a given query takes { query: object, // query object, see `find` sort: [object], // list of sort objects, see `find` diff --git a/pandora/edit/views.py b/pandora/edit/views.py index e1feafa87..38a283414 100644 --- a/pandora/edit/views.py +++ b/pandora/edit/views.py @@ -206,8 +206,7 @@ def sortClips(request, data): edit: string, // edit id sort: object // sort } - returns { - } + returns {} note: sort is [{key: string, operator: string}], operator can be '+' or '-' see: addClips, editClip, orderClips, removeClips ''' @@ -220,14 +219,16 @@ actions.register(sortClips, cache=False) def getEdit(request, data): ''' + Gets an edit by id takes { - id: - keys: [] + id: string, // edit id + keys: [string] // list of properties to return } returns { - id: - clips: + id: string, // edit id + clips: [object] // list of clips in this edit } + see: addEdit, editEdits, findEdits, removeEdit, sortEdits ''' if 'id' in data: response = json_response() @@ -253,7 +254,7 @@ def addEdit(request, data): id: string // edit id ... // more edit properties } - see: editEdit, findEdit, removeEdit, sortEdits + see: editEdit, findEdit, getEdit, removeEdit, sortEdits ''' data['name'] = re.sub(' \[\d+\]$', '', data.get('name', 'Untitled')).strip() name = data['name'] @@ -312,7 +313,7 @@ def editEdit(request, data): key: value, // property id and new value ... // more key/value pairs } - see: addEdit, findEdit, removeEdit, sortEdits + see: addEdit, findEdit, getEdit, removeEdit, sortEdits ''' edit = get_edit_or_404_json(data['id']) response = json_response() @@ -337,7 +338,7 @@ def removeEdit(request, data): id: string // edit id } returns {} - see: addEdit, editEdit findEdit, sortEdits + see: addEdit, editEdit, findEdit, getEdit, sortEdits ''' edit = get_edit_or_404_json(data['id']) response = json_response() @@ -388,20 +389,12 @@ def findEdits(request, data): range: [int, int], // range of results keys: [string] // list of properties to return } - - possible query keys: - name, user, featured, subscribed - - possible keys: - name, user, featured, subscribed, query - - } returns { - items: [object] + items: [object] // list of edit objects } notes: Possible query keys are 'featured', 'name', 'subscribed' and 'user', possible keys are 'featured', 'name', 'query', 'subscribed' and 'user'. - see: editEdits, find, removeEdit, sortEdits + see: addEdit, editEdits, find, getEdit, removeEdit, sortEdits ''' query = parse_query(data, request.user) @@ -494,7 +487,7 @@ def sortEdits(request, data): } returns {} notes: Sorting featured edits requires a specific per-user capability - see: editEdits, findEdits, removeEdit + see: addEdit, editEdits, findEdits, getEdit, removeEdit ''' position = 0 section = data['section'] diff --git a/pandora/entity/views.py b/pandora/entity/views.py index 8351e3b9a..9d3266e0f 100644 --- a/pandora/entity/views.py +++ b/pandora/entity/views.py @@ -209,18 +209,12 @@ def findEntities(request, data): range: [int, int], // range of results keys: [string] // list of properties to return } - - possible query keys: - name, type - - possible keys: - name, type, alternativeNames - - } returns { items: [object] } - see: addEntity, editEntity, getEntity, removeEntity + notes: Possible query keys are 'name' and 'type', possible keys are + 'alternativeNames', 'name' and 'type'. + see: addEntity, editEntity, find, getEntity, removeEntity ''' query = parse_query(data, request.user) diff --git a/pandora/event/views.py b/pandora/event/views.py index af9a07c57..c85101698 100644 --- a/pandora/event/views.py +++ b/pandora/event/views.py @@ -184,7 +184,7 @@ def findEvents(request, data): returns { items: [object] // list of items } - see: addEvent, editEvent, removeEvent + see: addEvent, editEvent, find, removeEvent ''' response = json_response(status=200, text='ok') query = parse_query(data, request.user) diff --git a/pandora/item/views.py b/pandora/item/views.py index 69b4827e1..f5fe0f6a1 100644 --- a/pandora/item/views.py +++ b/pandora/item/views.py @@ -161,10 +161,10 @@ def find(request, data): '$' (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, + responsive UI: 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. + For more examples, see https://wiki.0x2620.org/wiki/pandora/QuerySyntax. see: add, edit, get, lookup, remove, upload ''' if settings.JSON_DEBUG: diff --git a/pandora/itemlist/views.py b/pandora/itemlist/views.py index 3171e6bb5..753a3eb4f 100644 --- a/pandora/itemlist/views.py +++ b/pandora/itemlist/views.py @@ -58,24 +58,19 @@ def parse_query(data, user): def findLists(request, data): ''' + Finds lists for a given query 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 keys: - name, user, featured, subscribed, query - + range: [int, int], // range of results to return + keys: [string] // list of properties to return } returns { - items: [{name: string, user: string, featured: bool, public...}] + items: [object] // list of list objects } - see: addList, editList, getList, removeList, sortLists + notes: Possible query keys are 'featured', 'name', 'subscribed' and 'user', + possible keys are 'featured', 'name', 'query', 'subscribed' and 'user'. + see: addList, editList, find, getList, removeList, sortLists ''' query = parse_query(data, request.user) diff --git a/pandora/log/views.py b/pandora/log/views.py index b11243bbb..341792542 100644 --- a/pandora/log/views.py +++ b/pandora/log/views.py @@ -17,13 +17,14 @@ import models def logError(request, data): ''' - takes { - url: string, - line: string, - text: string - } - returns { - } + Logs an error + takes { + url: string, // URL + line: string, // line number + text: string // error text + } + returns {} + see: findErrorLogs, removeErrorLogs ''' if request.user.is_authenticated(): user = request.user @@ -49,10 +50,12 @@ actions.register(logError, cache=False) @admin_required_json def removeErrorLogs(request, data): ''' - takes { - ids: [string] - } - returns {} + Removes entries from the error log + takes { + ids: [string] // list of error ids + } + returns {} + see: findErrorLogs, logError ''' models.Log.objects.filter(id__in=[ox.fromAZ(i) for i in data['ids']]).delete() response = json_response() @@ -86,25 +89,17 @@ def order_query(qs, sort): @admin_required_json def findErrorLogs(request, data): ''' - takes { - query: { - conditions: [ - { - key: 'user', - value: 'something', - operator: '=' - } - ] - operator: "," - }, - sort: [{key: 'created', operator: '+'}], - range: [int, int] - keys: [string] - } - returns { - items: [object] - } - + Finds error logs 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 to return + keys: [string] // list of properties to return + } + returns { + items: [object] + } + see: find, logError, removeErrorLogs ''' response = json_response() diff --git a/pandora/news/views.py b/pandora/news/views.py index 8b95666c3..078089297 100644 --- a/pandora/news/views.py +++ b/pandora/news/views.py @@ -102,8 +102,8 @@ def editNews(request, data): title: string // title } returns { - id: string - ... + id: string // news item id + ... // more properties } see: addNews, getNews, removeNews ''' diff --git a/pandora/person/views.py b/pandora/person/views.py index afed07ff6..290f9ff75 100644 --- a/pandora/person/views.py +++ b/pandora/person/views.py @@ -19,15 +19,17 @@ from changelog.models import add_changelog @capability_required_json('canManageTitlesAndNames') def editName(request, data): ''' - takes { - id: id, - sortname: string - } - returns { - id: string, - name: string - ... - } + Edits the sort name for a given name + takes { + id: string, // name id + sortname: string // sort name + } + returns { + id: string, // name id + name: string // name + ... // more properties + } + see: findNames, sortName ''' person = get_object_or_404_json(models.Person, pk=ox.fromAZ(data['id'])) response = json_response() @@ -43,14 +45,16 @@ actions.register(editName, cache=False) def sortName(request, data): ''' - get sort name(s) for given name or names - takes { - names: [string] - name: string - } - returns { - name: sortName - } + Gets the sort name for one or more names + takes { + name: string, // either name + names: [string] // or list of names + } + returns { + name: sortName, // sort name for this name + ... // more results + } + see editName, findNames ''' names = data.get('names', []) if 'name' in data: @@ -92,56 +96,20 @@ def order_query(qs, sort): def findNames(request, data): ''' - takes { - query: { - conditions: [ - { - key: 'user', - value: 'something', - operator: '=' - } - ] - operator: "," - }, - itemsQuery: { - //see find request - }, - sort: [{key: 'name', operator: '+'}], - range: [0, 100] - keys: [] - } - - possible query keys: - name, numberofnames - - possible keys: - name, sortname, numberofnames - - returns { - items: [{name:, user:, featured:, public...}] - } - param data - {'query': query, 'sort': array, 'range': array} - - 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] - } + Finds names for a given query + takes { + query: object, // query object, see `find` + itemsQuery: object, // limit to matched items, query object, 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 + } + returns { + items: [object] // list of name objects + } + notes: Possible query keys are 'name' and 'numberofnames', possible keys + are 'name', 'numberofnames' and 'sortname'. + see: editName, find, sortName ''' response = json_response() diff --git a/pandora/title/views.py b/pandora/title/views.py index 55ed2cdd2..e9bdd581d 100644 --- a/pandora/title/views.py +++ b/pandora/title/views.py @@ -20,14 +20,16 @@ import models @capability_required_json('canManageTitlesAndNames') def editTitle(request, data): ''' - takes { - id: string - sorttitle: string - } - can contain any of the allowed keys for title - returns { - id: string - } + Edits the sort title for a given title + takes { + id: string, // name id + sorttitle: string // sort title + } + returns { + id: string, // title id + ... // more properties + } + see: findTitles ''' title = get_object_or_404_json(models.Title, pk=ox.fromAZ(data['id'])) response = json_response() @@ -71,59 +73,20 @@ def order_query(qs, sort): def findTitles(request, data): ''' - takes { - query: { - conditions: [ - { - key: 'user', - value: 'something', - operator: '=' - } - ] - operator: "," - }, - itemsQuery: { - //see find request - }, - sort: [{key: 'title', operator: '+'}], - range: [0, 100] - keys: [] - } - - possible query keys: - title, numberoftitles - - possible keys: - title, sorttitle, numberoftitles - - 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: [object]} - + Finds titles for a given query + takes { + query: object, // query object, see `find` + itemsQuery: object, // limit to matched items, query object, 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 + } + returns { + items: [object] // list of title objects + } + notes: Possible query keys are 'numberoftitles' and 'title', possible keys + are 'numberoftitles', 'sorttitle' and 'title'. + see: editTitle, find ''' response = json_response()