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

comparison doc/rest.txt @ 7801:af898d1d66dc

doc: run sphinx-lint over docs. Pointed out mutiple use of `x` where it should be ``x``. Also trailing whitespace and lines that are too long. Replaced all tabs by spaces. Also fixed spelling error while I was there. Fixed broken internal link.

author	John Rouillard <rouilj@ieee.org>
date	Wed, 13 Mar 2024 00:51:09 -0400
parents	835b248bf9fd
children	be6cb2e0d471

comparison

equal deleted inserted replaced

-:2d4684e4702d
+:af898d1d66dc
 .. meta::
 :description:
 Documentation on the RESTful interface to the Roundup Issue
-	Tracker. Enable REST access, endpoints, methods,
+Tracker. Enable REST access, endpoints, methods,
 authentication, discovery.
 .. index:: pair: api; Representational state transfer
 pair: api; rest
 CORS preflight requests are done using the OPTIONS method. They
 require that REST be enabled. These requests do not make any changes
 or get any information from the database. As a result they are
 available to the anonymous user and any authenticated user. The user
-does not need to have `Rest Access` permissions. Also these requests
+does not need to have ``Rest Access`` permissions. Also these requests
 bypass CSRF checks except for the Origin header check which is always
 run for preflight requests.
 You can permit only allowed ORIGINS by setting ``allowed_api_origins``
 in ``config.ini`` to the list of origins permitted to access your
 request fails, the api request will be stopped by the browser.
 The following CORS preflight headers are usually added automatically by
 the browser and must all be present:
-* `Access-Control-Request-Headers`
+* ``Access-Control-Request-Headers``
-* `Access-Control-Request-Method`
+* ``Access-Control-Request-Method``
-* `Origin`
+* ``Origin``
 The headers of the 204 response depend on the
 ``allowed_api_origins`` setting. If a ``*`` is included as the
 first element, any client can read the data but they can not
 provide authentication. This limits the available data to what
 the anonymous user can see in the web interface.
 All 204 responses will include the headers:
-* `Access-Control-Allow-Origin`
+* ``Access-Control-Allow-Origin``
-* `Access-Control-Allow-Headers`
+* ``Access-Control-Allow-Headers``
-* `Access-Control-Allow-Methods`
+* ``Access-Control-Allow-Methods``
-* `Access-Control-Max-Age: 86400`
+* ``Access-Control-Max-Age: 86400``
 If the client's ORIGIN header matches an entry besides ``*`` in the
 ``allowed_api_origins`` it will also include:
-* `Access-Control-Allow-Credentials: true`
+* ``Access-Control-Allow-Credentials: true``
 permitting the client to log in and perform authenticated operations.
-If the endpoint accepts the PATCH verb the header `Accept-Patch` with
+If the endpoint accepts the PATCH verb the header ``Accept-Patch`` with
 valid mime types (usually `application/x-www-form-urlencoded,
 multipart/form-data`) will be included.
 It will also include rate limit headers since the request is included
 in the rate limit for the URL.  The results from the CORS preflight
 from roundup import rest
 from dicttoxml import dicttoxml as dtox # from tracker_root/lib directory
 rest.dicttoxml = dtox
 .. _interfaces.py: customizing.html#interfaces-py-hooking-into-the-core-of-roundup
 The rest interface accepts the http accept header and can include
 ``q`` values to specify the preferred mechanism. This is the preferred
 way to specify alternate acceptable response formats.
 "meta data field1": "value",
 "meta data field2": "value",
 "collection": [
 { "link": "url to item",
 "id": "internal identifier for item" },
-	    { "link": "url to second item",
+{ "link": "url to second item",
 "id": "id item 2" },
 ... ]
 "@links": {
 "relation": [
 { "rel": "relation/subrelation",
 }
 }
 }
 available meta data is described in the documentation for the
 collections endpoint.
 The ``link`` fields implement `HATEOS`_ by supplying a url for the
 resource represented by that object. The "link" parameter with the
 value of a url is a special case of the @links parameter.
 "meta data field1": "value",
 "type": "type of item, issue, user ..."
 "link": "link to retrieve item",
 "attributes": {
 "title": "title of issue",
 "nosy": [
-	            { "link": "url for user4",
+{ "link": "url for user4",
 "id": "4" }
 ],
 ... }
 }
 giving the issue-id, e.g., ``/data/issue/42``. Individual properties of
 an item can be queried by appending the property, e.g.,
 ``/data/issue/42/title``.
 All the links mentioned in the following support the http method ``GET``.
 Results of a ``GET`` request will always return the results as a
 dictionary with the entry ``data`` referring to the returned data.
 Details are in the sections below.
 ``@total_size``. A a ``collection`` list follows which contains the id
 and link to the respective item.  For example a get on
 https://.../rest/data/issue returns::
 {
-	"data": {
+"data": {
-	    "collection": [
+"collection": [
-		{
+{
-		    "id": "1",
+"id": "1",
-		    "link": "https://.../rest/data/issue/1"
+"link": "https://.../rest/data/issue/1"
-		},
+},
-		{
+{
-		    "id": "100",
+"id": "100",
-		    "link": "https://.../rest/data/issue/100"
+"link": "https://.../rest/data/issue/100"
-		}
+}
-	...
+...
-	    ],
+],
-	    "@total_size": 171
+"@total_size": 171
-	}
+}
 }
 Collection endpoints support a number of features as seen in the next
 sections.
 Searching for strings (e.g. the issue title, or a keyword name)
 performs a case-insensitive substring search. Searching for
 ``title=Something`` (or in long form title~=Something) will find all
 issues with "Something" or "someThing", etc. in the title.
-Changing the search to ``title:=Something`` (note the `:`) performs an
+Changing the search to ``title:=Something`` (note the ``:``) performs an
 exact case-sensitive string match for exactly one word ``Something``
 with a capital ``S``. Another example is:
 ``title:=test+that+nosy+actually+works.`` where the + signs are spaces
 in the string. Replacing ``+`` with the `URL encoding`_ for space
 ``%20`` will also work. Note that you must match the spaces when
-performing exact matches. So `title:=test++that+nosy+actually+works.``
+performing exact matches. So ``title:=test++that+nosy+actually+works.``
-matches the word ``test`` with two spaces bewteen ``test`` and
+matches the word ``test`` with two spaces between ``test`` and
 ``that`` in the title.
 To make this clear, searching
 ``https://.../rest/data/issue?keyword=Foo`` will not work unless there
 is a keyword with a (case sensitive) name field of ``Foo`` which is
 Pagination
 ~~~~~~~~~~
 Collection endpoints support pagination. This is controlled by query
 parameters ``@page_size`` and ``@page_index`` (Note the use of the
-leading `@` to make the parameters distinguishable from field names.)
+leading ``@`` to make the parameters distinguishable from field names.)
 .. list-table:: Query Parameters Examples
 :header-rows: 1
 :widths: 20 80
 :class: valign-top
 Also when pagination is enabled the returned data include pagination
 links along side the collection data. This looks like::
 { "data":
 {
 "collection": { ... },
 "@total_size": 222,
 "@links": {
-	   "self": [
+"self": [
-	       {
+{
-		   "uri":
+"uri":
-	   "https://.../rest/data/issue?@page_index=1&@fields=status&@page_size=5",
+"https://.../rest/data/issue?@page_index=1&@fields=status&@page_size=5",
-		   "rel": "self"
+"rel": "self"
-	       }
+}
-	   ],
+],
-	   "next": [
+"next": [
-	       {
+{
-		   "uri":
+"uri":
-	   "https://.../rest/data/issue?@page_index=2&@fields=status&@page_size=5",
+"https://.../rest/data/issue?@page_index=2&@fields=status&@page_size=5",
-		   "rel": "next"
+"rel": "next"
-	       }
+}
-	   ]
+]
-	 }
+}
 }
 }
 The ``@links`` parameter is a dictionary indexed by
 relationships. Each relationship is a list of one or more full link
 ``https://.../rest/data/issue?@verbose=2&@fields=status`` returns::
 {
 "data": {
-	  "collection": [
+"collection": [
-	      {
+{
-		  "link": "https://.../rest/data/issue/1",
+"link": "https://.../rest/data/issue/1",
-		  "title": "Welcome to the tracker START HERE",
+"title": "Welcome to the tracker START HERE",
-		  "id": "1",
+"id": "1",
-		  "status": {
+"status": {
-		      "link": "https://.../rest/data/status/1",
+"link": "https://.../rest/data/status/1",
-		      "id": "1",
+"id": "1",
-		      "name": "new"
+"name": "new"
-		  }
+}
-	      },
+},
 ...
 }
 the format of the status field (included because of
 ``@fields=status``) includes the label for the status. This is due to
 inclusion of ``@verbose=2``. Without verbose you would see::
 {
 "data": {
-	  "collection": [
+"collection": [
-	      {
+{
-		  "link": "https://.../rest/data/issue/1",
+"link": "https://.../rest/data/issue/1",
-		  "id": "1",
+"id": "1",
-		  "status": {
+"status": {
-		      "link": "https://.../rest/data/status/1",
+"link": "https://.../rest/data/status/1",
-		      "id": "1"
+"id": "1"
-		  }
+}
-	      },
+},
 ...
 }
 Note that the ``link`` field that is returned doesn't exist in the
 database. It is a construct of the rest interface. This means that you
 {
 "data": {
 "id": "11",
 "type": "msg",
 "link": "https://.../demo/rest/data/msg/11",
-	"attributes": {
+"attributes": {
 "author": {
 "id": "5",
 "link": "https://.../demo/rest/data/user/5"
 },
 "content": {
 reprehenderit\neu to quisquam velit, passage,
 was or toil BC quis denouncing quia\nexercise,
 veritatis et used voluptas I elit, a The...",
 "date": "2017-10-30.00:53:15",
 ...
 Lines are wrapped for display, content value is one really long
 line. If the data is not utf-8 compatible, you will get a link.
 Retrieving the contents of a file is similar. Performing a
 get on ``https://.../demo/rest/data/file/11`` returns::
 ``https://.../demo/rest/data/file/11?@verbose=3`` the content field
 above is displayed as (wrapped for display)::
 "content": "file11 is not text, retrieve using binary_content
 property. mdsum: bd990c0f8833dd991daf610b81b62316",
 You can use the `binary_content property`_ described below to
 retrieve an encoded copy of the data.
 Other query params
 An example of returned values::
 {
 "data": {
-	  "type": "issue",
+"type": "issue",
-	  "@etag": "\"f15e6942f00a41960de45f9413684591\"",
+"@etag": "\"f15e6942f00a41960de45f9413684591\"",
-	  "link": "https://.../rest/data/issue/23",
+"link": "https://.../rest/data/issue/23",
-	  "attributes": {
+"attributes": {
-	      "keyword": [],
+"keyword": [],
-	      "messages": [
+"messages": [
-		  {
+{
-		      "link": "https://.../rest/data/msg/375",
+"link": "https://.../rest/data/msg/375",
-		      "id": "375"
+"id": "375"
-		  },
+},
-		  {
+{
-		      "link": "https://.../rest/data/msg/376",
+"link": "https://.../rest/data/msg/376",
-		      "id": "376"
+"id": "376"
-		  },
+},
-		  ...
+...
-	      ],
+],
-	      "files": [],
+"files": [],
-	      "status": {
+"status": {
-		  "link": "https://.../rest/data/status/2",
+"link": "https://.../rest/data/status/2",
-		  "id": "2"
+"id": "2"
-	      },
+},
-	      "title": "This is a title title",
+"title": "This is a title title",
-	      "superseder": [],
+"superseder": [],
-	      "nosy": [
+"nosy": [
-		  {
+{
-		      "link": "https://.../rest/data/user/4",
+"link": "https://.../rest/data/user/4",
-		      "id": "4"
+"id": "4"
-		  },
+},
-		  {
+{
-		      "link": "https://.../rest/data/user/5",
+"link": "https://.../rest/data/user/5",
-		      "id": "5"
+"id": "5"
-		  }
+}
-	      ],
+],
-	      "assignedto": null,
+"assignedto": null,
-	  },
+},
-	  "id": "23"
+"id": "23"
 }
 }
 Retrieve item using key value
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 "data": {
 "id": "12",
 "link": "https://.../demo/rest/data/file/12"
 }
 }
 Other Supported Methods for Items
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The method ``PUT`` is allowed on individual items, e.g.
 --data '{ "nosy": [ "1", "5" ] }' \
 "https://example.com/demo/rest/data/issue/23"
 {
 "data": {
-	  "attribute": {
+"attribute": {
-	      "nosy": [
+"nosy": [
-		  "1",
+"1",
-		  "5"
+"5"
-	      ]
+]
-	  },
+},
-	  "type": "issue",
+"type": "issue",
-	  "link": "https://example.com/demo/rest/data/issue/23",
+"link": "https://example.com/demo/rest/data/issue/23",
-	  "id": "23"
+"id": "23"
 }
 }
 If the above command is repeated with the data attribute::
 this is returned::
 {
 "data": {
-	  "attribute": {
+"attribute": {
-	      "title": "This is now my title"
+"title": "This is now my title"
-	  },
+},
-	  "type": "issue",
+"type": "issue",
-	  "link":
+"link":
 "https://.../demo/rest/data/issue/23",
-	  "id": "23"
+"id": "23"
 }
 }
 Note that nosy is not in the attributes returned. It is the same as
 before, so no change has happened and it is not reported.
 "https://.../demo/rest/data/issue/23"
 which returns both title and nosy attributes::
 {
-	"data": {
+"data": {
-	    "attribute": {
+"attribute": {
-		"title": "This is now my new title",
+"title": "This is now my new title",
-		"nosy": [
+"nosy": [
-		    "4",
+"4",
-		    "5"
+"5"
-		]
+]
-	    },
+},
-	    "type": "issue",
+"type": "issue",
-	    "link":
+"link":
-	    "https://.../demo/rest/data/issue/23",
+"https://.../demo/rest/data/issue/23",
-	    "id": "23"
+"id": "23"
-	}
+}
 }
 Note that mixing url query parameters with payload submission doesn't
 work. So using::
 which returns::
 {
 "data": {
-	  "attribute": {
+"attribute": {
-	      "nosy": [
+"nosy": [
-		  "3",
+"3",
-		  "4"
+"4"
-	      ]
+]
-	  },
+},
-	  "type": "issue",
+"type": "issue",
-	  "link": "https://.../rest/data/issue/23",
+"link": "https://.../rest/data/issue/23",
-	  "id": "23"
+"id": "23"
 }
 }
 Note that the changed values are returned so you can update
 internal state in your app with the new data.
 For example::
 {
 "data": {
-	  "link": "https://.../rest/data/issue/22/title",
+"link": "https://.../rest/data/issue/22/title",
-	  "data": "I need Broken PC",
+"data": "I need Broken PC",
-	  "type": "<class 'str'>",
+"type": "<class 'str'>",
-	  "id": "22",
+"id": "22",
-	  "@etag": "\"370510512b2d8fc3f98aac3d762cc7b1\""
+"@etag": "\"370510512b2d8fc3f98aac3d762cc7b1\""
 }
 }
 All endpoints support an ``OPTIONS`` method for determining which
 "link": "https://.../demo/rest/data/msg/11/content",
 "data": "of has to who pleasure. or of account give because the
 reprehenderit\neu to quisquam velit, passage, was or...",
 "@etag": "\"584f82231079e349031bbb853747df1c\""
 }
 }
 (the content property is wrapped for display, it is one long line.)
 .. _binary_content property:
 >>> import requests
 >>> u = 'http://user:password@tracker.example.com/demo/rest/data/'
 >>> s = requests.session()
-	>>> session.auth = ('admin', 'admin')
+>>> session.auth = ('admin', 'admin')
 >>> r = s.get(u + 'issue/42/title')
 >>> if r.status_code != 200:
 ...     print("Failed: %s: %s" % (r.status_code, r.reason))
 ...     exit(1)
 >>> print (r.json() ['data']['data']
 >>> r = s.get (u + 'issue/42')
 >>> etag = r.headers['ETag']
 >>> print("ETag: %s" % etag)
 >>> etag = r.json()['data']['@etag']
 >>> print("@etag: %s" % etag)
 >>> h = {'If-Match': etag,
 ...   'X-Requested-With': 'rest',
 ...   'Referer': 'http://tracker.example.com/demo/'}
 >>> d = {'@op:'action', '@action_name':'retire'}
 >>> r = s.patch(u + 'issue/42', data = d, headers = h)
 >>> print(r.json())
 A similar curl based retire example is to use::
 curl -s -u admin:admin \
 -H "Referer: https://tracker.example.com/demo/" \
-	-H "X-requested-with: rest"  \
+-H "X-requested-with: rest"  \
-	-H "Content-Type: application/json" \
+-H "Content-Type: application/json" \
-	https://tracker.example.com/demo/rest/data/status/1
+https://tracker.example.com/demo/rest/data/status/1
 to get the etag manually. Then insert the etag in the If-Match header
 for this retire example::
 curl -s -u admin:admin \
 -H "Referer: https://tracker.example.com/demo/" \
-	-H "X-requested-with: rest"  \
+-H "X-requested-with: rest"  \
-	-H "Content-Type: application/json" \
+-H "Content-Type: application/json" \
-	-H 'If-Match: "a502faf4d6b8e3897c4ecd66b5597571"' \
+-H 'If-Match: "a502faf4d6b8e3897c4ecd66b5597571"' \
-	--data-raw '{ "@op":"action", "@action_name": "retire" }'\
+--data-raw '{ "@op":"action", "@action_name": "retire" }'\
-	-X PATCH \
+-X PATCH \
-	https://tracker.example.com/demo/rest/data/status/1
+https://tracker.example.com/demo/rest/data/status/1
 and restore::
 curl -s -u admin:admin \
 -H "Referer: https://tracker.example.com/demo/" \
-	-H "X-requested-with: rest"  \
+-H "X-requested-with: rest"  \
-	-H "Content-Type: application/json" \
+-H "Content-Type: application/json" \
-	-H 'If-Match: "a502faf4d6b8e3897c4ecd66b5597571"' \
+-H 'If-Match: "a502faf4d6b8e3897c4ecd66b5597571"' \
-	--data-raw '{ "@op":"action", "@action_name": "restore" }'\
+--data-raw '{ "@op":"action", "@action_name": "restore" }'\
-	-X PATCH \
+-X PATCH \
-	https://tracker.example.com/demo/rest/data/status/1
+https://tracker.example.com/demo/rest/data/status/1
 Searches and selection
 ----------------------
 Consider a multi-select box for the superseder property.  Using
 selectize.js (and jquery) code similar to::
 $('#superseder').selectize({
-	valueField: 'id',
+valueField: 'id',
-	labelField: 'title',
+labelField: 'title',
-	searchField: 'title', ...
+searchField: 'title', ...
-	load: function(query, callback) {
+load: function(query, callback) {
-		if (!query.length) return callback();
+if (!query.length) return callback();
-		$.ajax({
+$.ajax({
-			url: '.../rest/data/issue?@verbose=2&title='
+url: '.../rest/data/issue?@verbose=2&title='
-			    + encodeURIComponent(query),
++ encodeURIComponent(query),
-			type: 'GET',
+type: 'GET',
-			error: function() {callback();},
+error: function() {callback();},
-			success: function(res) {
+success: function(res) {
-			  callback(res.data.collection);}
+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``
 {
 "data": {
 "@total_size": 440,
 "collection": [
 {
-	  "link": ".../rest/data/issue/8",
+"link": ".../rest/data/issue/8",
-	  "id": "8",
+"id": "8",
-	  "title": "Request for Power plugs"
+"title": "Request for Power plugs"
 },
 {
-	  "link": ".../rest/data/issue/27",
+"link": ".../rest/data/issue/27",
-	  "id": "27",
+"id": "27",
-	  "title": "Request for foo"
+"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
 from roundup.rest import Routing, RestfulInstance, _data_decorator
 from roundup.exceptions import Unauthorised
 class RestfulInstance:
-	@Routing.route("/summary2")
+@Routing.route("/summary2")
-	@_data_decorator
+@_data_decorator
-	def summary2(self, input):
+def summary2(self, input):
-	    result = { "hello": "world" }
+result = { "hello": "world" }
-	    return 200, result
+return 200, result
 will make a new endpoint .../rest/summary2 that you can test with::
 $ curl -X GET .../rest/summary2
 {
 Similarly appending this to interfaces.py after summary2::
 # handle more endpoints
 @Routing.route("/data/<:class_name>/@schema", 'GET')
 def get_element_schema(self, class_name, input):
-	    result = { "schema": {} }
+result = { "schema": {} }
-	    uid = self.db.getuid ()
+uid = self.db.getuid ()
-	    if not self.db.security.hasPermission('View', uid, class_name) :
+if not self.db.security.hasPermission('View', uid, class_name) :
-		raise Unauthorised('Permission to view %s denied' % class_name)
+raise Unauthorised('Permission to view %s denied' % class_name)
-	    class_obj = self.db.getclass(class_name)
+class_obj = self.db.getclass(class_name)
-	    props = class_obj.getprops(protected=False)
+props = class_obj.getprops(protected=False)
-	    schema = result['schema']
+schema = result['schema']
-	    for prop in props:
+for prop in props:
-		schema[prop] = { "type": repr(class_obj.properties[prop]) }
+schema[prop] = { "type": repr(class_obj.properties[prop]) }
-	    return result
+return result
 ..
 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": {
+"schema": {
-	    "keyword": {
+"keyword": {
-		"type": "<roundup.hyperdb.Multilink to \"keyword\">"
+"type": "<roundup.hyperdb.Multilink to \"keyword\">"
-	    },
+},
-	    "title": {
+"title": {
-		"type": "<roundup.hyperdb.String>"
+"type": "<roundup.hyperdb.String>"
-	    },
+},
-	    "files": {
+"files": {
-		"type": "<roundup.hyperdb.Multilink to \"file\">"
+"type": "<roundup.hyperdb.Multilink to \"file\">"
-	    },
+},
-	    "status": {
+"status": {
-		"type": "<roundup.hyperdb.Link to \"status\">"
+"type": "<roundup.hyperdb.Link to \"status\">"
-	    }, ...
+}, ...
-	}
+}
 }
 Adding other endpoints (e.g. to allow an OPTIONS query against
 ``/data/issue/@schema``) is left as an exercise for the reader.
 However the templating system can access the hyperdb directly which
 allows filtering to happen with admin privs escaping the standard
 permissions scheme. For example access to a user's roles should be
 limited to the user (read only) and an admin.  If you have customised
 your schema to implement `Restricting the list of
-users that are assignable to a task <customizing.html#restricting-the-list-of-users-that-are-assignable-to-a-task>`__
+users that are assignable to a task
+<customizing.html#restricting-the-list-of-users-that-are-assignable-to-a-task>`__
 so that only users with a
 Developer role are allowed to be assigned to an issue, a rest end
 point must be added to provide a view that exposes users with this
 permission.
 Using the normal ``/data/user?roles=Developer`` will return all the
 users in the system unless you are an admin user because most users
 can't see the roles. Building on the `Adding new rest endpoints`_
-section this code adds a new endpoint `/data/@permission/Developer`
+section this code adds a new endpoint ``/data/@permission/Developer``
 that returns a list of users with the developer role::
 from roundup.rest import Routing, RestfulInstance
 from roundup.anypy.cgi_ import MiniFieldStorage
 class RestfulInstance(object):
-	@Routing.route("/data/@permission/Developer")
+@Routing.route("/data/@permission/Developer")
-	def get_role_Developer(self, input):
+def get_role_Developer(self, input):
-	    '''An endpoint to return a list of users with Developer
+'''An endpoint to return a list of users with Developer
-	       role who can be assigned to an issue.
+role who can be assigned to an issue.
-	       It ignores attempt to search by any property except
+It ignores attempt to search by any property except
-	       username and realname. It also ignores the whole @fields
+username and realname. It also ignores the whole @fields
-	       specification if it specifies a property the user
+specification if it specifies a property the user
-	       can't view. Other @ query params (e.g. @page... and
+can't view. Other @ query params (e.g. @page... and
-	       @verbose) are supported.
+@verbose) are supported.
-	       It assumes admin access rights so that the roles property
+It assumes admin access rights so that the roles property
-	       of the user can be searched. This is needed if the roles
+of the user can be searched. This is needed if the roles
-	       property is not searchable/viewable by normal users. A user
+property is not searchable/viewable by normal users. A user
-	       who can search roles can identify users with the admin
+who can search roles can identify users with the admin
-	       role. So it does not respond the same as a rest/data/users
+role. So it does not respond the same as a rest/data/users
-	       search by a non-admin user.
+search by a non-admin user.
-	    '''
+'''
-	    # get real user id
+# get real user id
-	    realuid=self.db.getuid()
+realuid=self.db.getuid()
-	    def allowed_field(fs):
+def allowed_field(fs):
-		if fs.name in ['username', 'realname' ]:
+if fs.name in ['username', 'realname' ]:
-		    # only allow search matches for these fields
+# only allow search matches for these fields
-		    return True
+return True
-		elif fs.name in [ '@fields' ]:
+elif fs.name in [ '@fields' ]:
-		    for prop in fs.value.split(','):
+for prop in fs.value.split(','):
-			# if any property is unviewable to user, remove
+# if any property is unviewable to user, remove
-			# @field entry. If they can't see it for the admin
+# @field entry. If they can't see it for the admin
-			# user, don't let them see it for any user.
+# user, don't let them see it for any user.
-			if not self.db.security.hasPermission(
+if not self.db.security.hasPermission(
-				'View', realuid, 'user', property=prop,
+'View', realuid, 'user', property=prop,
-				itemid='1'):
+itemid='1'):
-			    return False
+return False
-		    return True
+return True
-		elif fs.name.startswith("@"):
+elif fs.name.startswith("@"):
-		    # allow @page..., @verbose etc.
+# allow @page..., @verbose etc.
-		    return True
+return True
-		# deny all other url parmeters
+# deny all other url parmeters
-		return False
+return False
-	    # Cleanup input.list to prevent user from probing roles
+# Cleanup input.list to prevent user from probing roles
-	    # or viewing things the user should not be able to view.
+# or viewing things the user should not be able to view.
-	    input.list[:] = [ fs for fs in input.list
+input.list[:] = [ fs for fs in input.list
-			      if allowed_field(fs) ]
+if allowed_field(fs) ]
-	    # Add the role filter required to implement the permission
+# Add the role filter required to implement the permission
-	    # search
+# search
-	    input.list.append(MiniFieldStorage("roles", "Developer"))
+input.list.append(MiniFieldStorage("roles", "Developer"))
-	    # change user to acquire permission to search roles
+# change user to acquire permission to search roles
-	    self.db.setCurrentUser('admin')
+self.db.setCurrentUser('admin')
-	    # Once we have cleaned up the request, pass it to
+# Once we have cleaned up the request, pass it to
-	    # get_collection as though /rest/data/users?... has been called
+# get_collection as though /rest/data/users?... has been called
-	    # to get @verbose and other args supported.
+# to get @verbose and other args supported.
-	    return self.get_collection('user', input)
+return self.get_collection('user', input)
 Calling this with::
 curl 'http://example.com/demo/rest/data/@permission/Developer?@fields=realname&roles=Users&@verbose=2'
 produces output similar to::
 {
-	"data": {
+"data": {
-	    "collection": [
+"collection": [
-		{
+{
-		    "username": "agent",
+"username": "agent",
-		    "link": http://example.com/demo/rest/data/user/4",
+"link": http://example.com/demo/rest/data/user/4",
 "realname": "James Bond",
-		    "id": "4"
+"id": "4"
-		}
+}
-	    ],
+],
-	    "@total_size": 1
+"@total_size": 1
-	}
+}
 }
 assuming user 4 is the only user with the Developer role. Note that
 the url passes the ``roles=User`` filter option which is silently
 ignored.
 timelog links to the ``times`` property of the issue.
 Create role
 ~~~~~~~~~~~
-Adding this snippet of code to the tracker's ``schema.py`` should create a role with the
+Adding this snippet of code to the tracker's ``schema.py`` should
-proper authorization::
+create a role with the proper authorization::
 db.security.addRole(name="User:timelog",
 description="allow a user to create and append timelogs")
 db.security.addPermissionToRole('User:timelog', 'Rest Access')
 else:
 claim['roles'] = user_roles
 secret = self.db.config.WEB_JWT_SECRET
 myjwt = jwt.encode(claim, secret, algorithm='HS256')
-	    # if jwt.__version__ >= 2.0.0 jwt.encode() returns string
+# if jwt.__version__ >= 2.0.0 jwt.encode() returns string
-	    # not byte. So do not use b2s() with newer versions of pyjwt.
+# not byte. So do not use b2s() with newer versions of pyjwt.
 result = {"jwt": b2s(myjwt),
 }
 return 200, result
 curl -s -H "Referer: https://.../demo/" \
 -H "X-requested-with: rest" \
 https://.../demo/rest/JWT/validate?JWT=eyJ0eXAiOiJK...XxMDb-Q3oCnMpyhxPXMAk
 (note no login is required) which returns::
 {
 "data": {
 "user": "3",
 "roles": [
 "user:timelog"
 "iss": "https://.../demo/",
 "aud": "https://.../demo/",
 "iat": 1569542404,
 "exp": 1569546004
 }
 }
 There is an issue for `thoughts on JWT credentials`_ that you can view
 for ideas or add your own.
 uid = self.db.getuid()
 class_obj = self.db.getclass('user')
 node = class_obj.getnode(uid)
-	    # set value to 0 to use WEB_API_CALLS_PER_INTERVAL
+# set value to 0 to use WEB_API_CALLS_PER_INTERVAL
-	    user_calls = node.__getattr__('rate_limit_calls')
+user_calls = node.__getattr__('rate_limit_calls')
-	    # set to 0 to use WEB_API_INTERVAL_IN_SEC
+# set to 0 to use WEB_API_INTERVAL_IN_SEC
-	    user_interval = node.__getattr__('rate_limit_interval')
+user_interval = node.__getattr__('rate_limit_interval')
 return RateLimit(user_calls or calls,
-	       	   timedelta(seconds=(user_interval or interval)))
+timedelta(seconds=(user_interval or interval)))
 else:
 # disable rate limiting if either parameter is 0
 return None
 RestfulInstance.getRateLimit = grl

Mercurial > p > roundup > code

comparison doc/rest.txt @ 7801:af898d1d66dc