Mercurial Repository: p/roundup/code: doc/rest.txt comparison

comparison doc/rest.txt @ 5695:3e1b66c4e1e2

Update docs. Correct errors reported by setup.py build_docs. Add rest interface and link to rest doc to features page. Add link to xmlrpc doc to features page. Add rest doc to index. Update rest doc, hopefully clarify confusing use of parameters in patch action section. Fix code examples in "Adding new rest endpoints" section. Fix example adding import of exception.

author	John Rouillard <rouilj@ieee.org>
date	Sun, 07 Apr 2019 20:17:52 -0400
parents	1b9ef04b9528
children	c7dd1cae3416

comparison

equal deleted inserted replaced

-:c3ffa1ef6b7f
+:3e1b66c4e1e2
 from relative REST-API links for brevety.
 Summary
 =======
-A Summary page can be reached via ``/data/summary`` via the ``GET`` method.
+A Summary page can be reached via ``/summary`` via the ``GET`` method.
 This is currently hard-coded for the standard tracker schema shipped
 with roundup and will display a summary of open issues.
 Data
 ====
 list. The same effect can be achieved with a ``PUT`` request and an
 empty new value.
 Finally the ``PATCH`` method can be applied to individual items, e.g.,
 ``/data/issue/42`` and to properties, e.g., ``/data/issue/42/title``.
-This method gets an operator ``@op=<method>`` where ``<method`` is one
+This method gets an operator ``@op=<method>`` where ``<method>`` is one
 of ``add``, ``replace``, ``remove``, only for an item (not for a
 property) an additional operator ``action`` is supported. If no operator
 is specified, the default is ``replace``. The first three operators are
 self explanatory. For an ``action`` operator an ``@action_name`` and
 optional ``@action_argsXXX`` parameters have to be supplied. Currently
-there are only two actions without parameters, namely ``retire`` and
+there are only two actions, neither has args, namely ``retire`` and
 ``restore``. The ``retire`` action on an item is the same as a
 ``DELETE`` method, it retires the item. The ``restore`` action is the
 inverse of ``retire``, the item is again visible.
 On success the returned value is the same as the respective ``GET``
 method.
 =========================
 Add or edit the file interfaces.py at the root of the tracker
 directory.
-In that file add (remove indentation):
+In that file add::
 from roundup.rest import Routing, RestfulInstance, _data_decorator
+from roundup.exceptions import Unauthorised
 class RestfulInstance:
 	@Routing.route("/summary2")
 	@_data_decorator
 	def summary2(self, input):
 	    result = { "hello": "world" }
 	    return 200, result
-will make a new endpoint .../rest/summary2 that you can test with:
+will make a new endpoint .../rest/summary2 that you can test with::
 $ curl -X GET .../rest/summary2
 {
 "data": {
 "hello": "world"
 }
 }
-Similarly appending this to interfaces.py after summary2:
+Similarly appending this to interfaces.py after summary2::
-@Routing.route("/data/<:class_name>/@schema", 'GET')
+# handle more endpoints
-def get_element_schema(self, class_name, input):
+@Routing.route("/data/<:class_name>/@schema", 'GET')
-result = { "schema": {} }
+def get_element_schema(self, class_name, input):
-uid = self.db.getuid ()
+	    result = { "schema": {} }
-if not self.db.security.hasPermission('View', uid, class_name) :
+	    uid = self.db.getuid ()
-raise Unauthorised('Permission to view %s denied' % class_name)
+	    if not self.db.security.hasPermission('View', uid, class_name) :
+		raise Unauthorised('Permission to view %s denied' % class_name)
-class_obj = self.db.getclass(class_name)
-props = class_obj.getprops(protected=False)
+	    class_obj = self.db.getclass(class_name)
-schema = result['schema']
+	    props = class_obj.getprops(protected=False)
+	    schema = result['schema']
-for prop in props:
-schema[prop] = { "type": repr(class_obj.properties[prop]) }
+	    for prop in props:
+		schema[prop] = { "type": repr(class_obj.properties[prop]) }
-return result
+	    return result
-returns some data about the class
+..
+the # comment in the example is needed to preserve indention under Class.
+returns some data about the class::
 $ curl -X GET .../rest/data/issue/@schema
 {
 	"schema": {
 	    "keyword": {
 	    }, ...
 	}
 }
+Adding other endpoints (e.g. to allow an OPTIONS query against
+``/data/issue/@schema``) is left as an exercise for the reader.
 Searches and selection
 ======================
 One difficult interface issue is selection of items from a long list.
 Using multi-item selects requires loading a lot of data (e.g. consider
 This can be made easier using javascript selection tools like select2,
 selectize.js, chosen etc. These tools can query a remote data provider
 to get a list of items for the user to select from.
 Consider a multi-select box for the superseder property.  Using
-selectize.js (and jquery) code similar to:
+selectize.js (and jquery) code similar to::
 $('#superseder').selectize({
 	valueField: 'id',
 	labelField: 'title',
 	searchField: 'title', ...
 	load: function(query, callback) {
 		if (!query.length) return callback();
 			success: function(res) {
 			  callback(res.data.collection);}
 Sets up a box that a user can type the word "request" into. Then
 selectize.js will use that word to generate an ajax request with the
-url: .../rest/data/issue?@verbose=2&title=request
+url: ``.../rest/data/issue?@verbose=2&title=request``
-This will return data like:
+This will return data like::
 {
 "data": {
 "@total_size": 440,
 "collection": [
 {
 	  "link": ".../rest/data/issue/27",
 	  "id": "27",
 	  "title": "Request for foo"
 },
+...
 selectize.js will look at these objects (as passed to
 callback(res.data.collection)) and create a select list from the each
 object showing the user the labelField (title) for each object and
 associating each title with the corresponding valueField (id). The
 example above has 440 issues returned from a total of 2000
 issues. Only 440 had the word "request" somewhere in the title greatly
 reducing the amount of data that needed to be transferred.
-Similar things can be set up to search a large list of keywords using
+Similar code can be set up to search a large list of keywords using::
 .../rest/data/keyword?@verbose=2&name=some
 which would return: "some keyword" "awesome" "somebody" making
 selections for links and multilinks much easier.
 Hopefully future enhancements will allow get on a collection to
 include other fields. Why do we want this?  Selectize.js can set up
 option groups (optgroups) in the select pulldown. So by including
-status in the returned data:
+status in the returned data::
 {
 	  "link": ".../rest/data/issue/27",
 	  "id": "27",
 	  "title": "Request for foo",
 	  'status": "open"
 },
-a select widget like:
+a select widget like::
 === New ===
 A request
 === Open ===
 Request for bar

Mercurial > p > roundup > code

comparison doc/rest.txt @ 5695:3e1b66c4e1e2