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

comparison doc/rest.txt @ 7473:f8b5b0310f88

I think headings are consistant now.

author	John Rouillard <rouilj@ieee.org>
date	Thu, 08 Jun 2023 09:27:17 -0400
parents	f53de10ea8ea
children	a072331c843b

comparison

equal deleted inserted replaced

-:db58a86aa29d
+:f8b5b0310f88
 .. contents::
 :local:
 :depth: 3
 Introduction
-------------
+============
 After the last 1.6.0 Release, a REST-API developed in 2015 during a
 Google Summer of Code (GSOC) by Chau Nguyen, supervised by Ezio
 Melotti was integrated. The code was updated by Ralf Schlatterbeck
 and John Rouillard to fix some shortcomings and provide the necessary
 functions for a single page web application, e.g. etag support,
 pagination, field embedding among others.
 Enabling the REST API
----------------------
+=====================
 The REST API can be disabled in the ``[web]`` section of ``config.ini``
 via the variable ``enable_rest`` which is ``yes`` by default.
 Users have to be authorized to use the rest api. The user must have
 explicitly set.)
 .. _upgrading directions: upgrading.html
 Preventing CSRF Attacks
-=======================
+-----------------------
 Clients should set the header X-REQUESTED-WITH to any value and the
 tracker's config.ini should have ``csrf_enforce_header_x-requested-with
 = yes`` or ``required``.
 that is not hosted at the same origin as Roundup, you must permit
 the origin using the ``allowed_api_origins`` setting in
 ``config.ini``.
 Rate Limiting the API
-=====================
+---------------------
 This is a work in progress. This version of roundup includes Rate
 Limiting for the API (which is different from rate limiting login
 attempts on the web interface).
 Also the rate limit is a little lossy. Under heavy load, it is
 possible for it to miscount allowing more than burst count. Errors of
 up to 10% have been seen on slower hardware.
 Client API
-----------
+==========
 The top-level REST url ``/rest/`` will display the current version of
 the REST API (Version 1 as of this writing) and some links to relevant
 endpoints of the API. In the following the ``/rest`` prefix is omitted
 from relative REST-API links for brevity.
 Headers
-=======
+-------
 If rate limiting is enabled there are 3 "standard" headers:
 **X-RateLimit-Limit**:  Calls allowed per period.
 the REST endpoint will be going away. See
 https://www.rfc-editor.org/rfc/rfc8594 for details on this header and
 the sunset link type.
 Hyperdb Stats
-=============
+-------------
 Adding ``@stats=true`` as a GET query parameter or POST data item will
 augment the response with an ``@stats`` dictionary. Any value other
 than ``true`` (any case) will disable the ``@stats`` dictionary. When
 stats are enabled the response includes an ``@stats`` member and looks
 stats are not shown. The fields are subject to change. An
 understanding of the code is recommended if you are going to use this
 info.
 Versioning
-==========
+----------
 Currently there is only one version of the API. Versions are simple
 integers. The current version is ``1``. Version selection is
 implemented in the server using one of three methods:
 If an explicit version is not provided, the server default is used.
 The server default is reported by querying the ``/rest/`` endpoint as
 described above.
 Input Formats
-=============
+-------------
 For a GET or OPTIONS request, the Content-Type header should
 not be sent.
 Otherwise Content-Type is allowed to be ``application/json`` or
 ``application/x-www-form-urlencoded``. Any other value returns error
 code 415.
 CORS preflight requests
-^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~
 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
 cause a problem. If it is an issue, you can see
 `Creating Custom Rate Limits`_
 and craft a rate limiter that ignores anonymous OPTIONS requests.
 Response Formats
-================
+----------------
 The default response format is json.
 If you add the ``dicttoxml.py`` module you can request XML formatted
 data using the header ``Accept: application/xml`` in your
 extension.  You will also get a 406 status if none of the entries in
 the accept header are available or if the accept header is invalid.
 General Guidelines
-==================
+------------------
 Performing a ``GET`` on an item or property of an item will return an
 ETag header or an @etag property. This needs to be submitted with
 ``DELETE``, ``PUT`` and ``PATCH`` operations on the item using an
 ``If-Match`` header or an ``"@etag`` property in the data payload if
 }
 }
 Special Endpoints
-=================
+-----------------
 There are a few special endpoints that provide some additional data.
 Tracker administrators can add new endpoints. See
 "Programming the REST API"_ below.
 /summary
-^^^^^^^^
+~~~~~~~~
 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
-^^^^^
+~~~~~
 This is the primary entry point for data from the tracker.
 The ``/data`` link will display a set of classes of the tracker. All
 classes can be reached via ``/data/<classname>`` where ``<classname>``
 dictionary with the entry ``data`` referring to the returned data.
 Details are in the sections below.
 /data/\ *class* Collection
-==========================
+--------------------------
 When performing the ``GET`` method on a class (e.g. ``/data/issue``),
 the ``data`` object includes the number of items available in
 ``@total_size``. A a ``collection`` list follows which contains the id
 and link to the respective item.  For example a get on
 a result all clients must be programmed to expect pagination
 decorations in the response. See the section on pagination below for
 details.
 Searching
-^^^^^^^^^
+~~~~~~~~~
 Searching is done by adding roundup field names and values as query
 parameters. Using: https://.../rest/data/issue you can search using:
 .. list-table:: Query Parameters Examples
 body of a msg) is a work in progress.
 .. _URL Encoding: https://en.wikipedia.org/wiki/Percent-encoding
 Transitive Searching
-~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^
 In addition to searching an issue by its properties, you can search
 for issues where linked items have a certain property. For example
 using ``/issues?messages.author=1`` will find all issues that include
 (link to) a message created by the admin user. This can also be done
 user. Note that users can search a field even if they can't view
 it. However they may be able to use searches to discover the value of
 the field even if they can't view it.
 Sorting
-^^^^^^^
+~~~~~~~
 Collection endpoints support sorting. This is controlled by specifying a
 ``@sort`` parameter with a list of properties of the searched class.
 Optionally properties can include a sign ('+' or '-') to specify
 ascending or descending sort, respectively. If no sign is given,
 @sort=status,-id
 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.)
 entries in the collection as a DOS prevention measure. As a result
 clients must be prepared to handle the incomplete response and request
 the next URL to retrieve all of the entries.
 Field embedding and verbose output
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 In collections, you can specify what fields should be embedded in the
 returned data. There are some shortcuts provided using the
 ``@verbose`` parameter. All the examples in this section are for a GET
 operation on ``https://.../rest/data/issue``.
 See the `Searches and selection`_ section for the use cases supported
 by these features.
 Getting Message and Files Content
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 You can retreive a message with a url like
 ``https://.../demo/rest/data/msg/11``. This returns something like::
 {
 You can use the `binary_content property`_ described below to
 retrieve an encoded copy of the data.
 Other query params
-^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~
 This table lists other supported parameters:
 .. list-table:: Query Parameters Examples
 :header-rows: 1
 You can disable pretty printing by using this query parameter.
 Note the default is true, so @pretty=true is not supported at
 this time.
 Using the POST method
-^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~
 Only class links support the ``POST`` method for creation of new items
 of a class, e.g., a new issue via the ``/data/issue`` link. The post
 gets a dictionary of keys/values for the new item. It returns the same
 parameters as the GET method after successful creation.
 return a 400 error. This is meant to allow the client (a time
 limited way) to retrieve the created resource if the
 response was lost.
 Other Supported Methods for Collections
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Supports the ``OPTIONS`` method for determining which methods are
 allowed on a given endpoint.
 Does not support PUT, DELETE or PATCH.
 /data/\ *class*/\ *id* item
-===========================
+---------------------------
 When performing the ``GET`` method on an item
 (e.g. ``/data/issue/42``), a ``link`` attribute contains the link to
 the item, ``id`` contains the id, ``type`` contains the class name
 (e.g. ``issue`` in the example) and an ``etag`` property can be used
 	  "id": "23"
 }
 }
 Retrieve item using key value
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 If the class has a key attribute, e.g. the 'status' class in the
 classic tracker, it can be used to retrieve the item.
 You can get an individual status by specifying the key-attribute value
 The long-form (with ``=``) is different from a query-parameter like
 ``/data/status?name=closed`` which would find all stati (statuses)
 that have ``closed`` as a substring.
 Dealing with Messages and Files
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Using the requests library you can upload a file using::
 d = dict (name = filename, content = content, type = content_type)
 j = self.post ('file', data = d)
 }
 }
 Other Supported Methods for Items
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The method ``PUT`` is allowed on individual items, e.g.
 ``/data/issue/42`` On success it returns the same parameters as the
 respective ``GET`` method. Note that for ``PUT`` an Etag has to be
 supplied, either in the request header or as an @etag parameter. An
 ``If-Match`` header. If you are using ``PUT`` or ``PATCH`` an
 ``@etag`` value can be supplied in the payload in place of the
 ``If-Match`` header.
 /data/\ *class*/\ *id*/\ *property* field
-=========================================
+-----------------------------------------
 A ``GET`` method on a property (e.g. ``/data/issue/42/title``) returns the
 link, an ``@etag``, the type of the property (e.g. "<type str>") the id
 of the item and the content of the property in ``data``.
 All endpoints support an ``OPTIONS`` method for determining which
 methods are allowed on a given endpoint.
 Message and File Content
-^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~
 Messages and files have content properties. If the data is utf-8
 compatible (e.g. an email message) you can retrieve it with
 rest/data/msg/11/content to obtain::
 The data is a json encoded hexidecimal representation of the data.
 Other Supported Methods for fields
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The method ``PUT`` is allowed on a property e.g.,
 ``/data/issue/42/title``. On success it returns the same parameters as
 the respective ``GET`` method. Note that for ``PUT`` an Etag has to be
 supplied, either in the request header or as an @etag parameter.
 ``If-Match`` header. If you are using ``PUT`` or ``PATCH`` an
 ``@etag`` value can be supplied in the payload in place of the
 ``If-Match`` header.
 Tunneling Methods via POST
-==========================
+--------------------------
 If you are working through a proxy and unable to use http methods like
 PUT, PATCH, or DELETE, you can use POST to perform the action. To tunnel
 an action through POST, send the ``X-HTTP-METHOD-OVERRIDE`` header
 with a value of DELETE or other capitalized HTTP verb. The body of the
 POST should be what you would send if you were using the method
 without tunneling.
 Examples and Use Cases
-----------------------
+======================
 sample python client
-====================
+--------------------
 The client uses the python ``requests`` library for easier interaction
 with a REST API supporting JSON encoding::
 	-X PATCH \
 	https://tracker.example.com/demo/rest/data/status/1
 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
 a selection tool to select one or more issues as in the classic
 superseder field).
 etc. can be generated. Also depending on the javascript library, other
 fields can be used for subsearch and sorting.
 Programming the REST API
-------------------------
+========================
 You can extend the rest api for a tracker. This describes how to add
 new rest end points. At some point it will also describe the rest.py
 structure and implementation.
 Adding new rest endpoints
-=========================
+-------------------------
 Add or edit the file `interfaces.py`_ at the root of the tracker
 directory.
 In that file add::
 Adding other endpoints (e.g. to allow an OPTIONS query against
 ``/data/issue/@schema``) is left as an exercise for the reader.
 Redefine/move rest endpoints
-============================
+----------------------------
 In addition to adding new endpoints, you can redefine existing
 endpoints. Adding this as described above::
 @Routing.route("/summary")
 will make the response at /rest/data2/<class> be the same as what is
 normally at /rest/data/<class>.
 Controlling Access to Backend Data
-==================================
+----------------------------------
 Roundup's schema is the primary access control mechanism. Roles and
 Permissions provide the ability to carefully control what data can be
 seen.
 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.
 Changing Access Roles with JSON Web Tokens
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+------------------------------------------
 As discussed above Roundup's schema is the access control mechanism.
 However you may want to integrate a third party system with roundup.
 E.G. suppose you use a time tracking service that takes an issue id
 and keeps a running count of how much time was spent on it. Then with
 for ideas or add your own.
 .. _thoughts on JWT credentials: https://issues.roundup-tracker.org/issue2551064
 Final steps
-^^^^^^^^^^^
+~~~~~~~~~~~
 See the `upgrading directions`_ on how to use the ``updateconfig``
 command to generate an updated copy of config.ini using
 roundup-admin. Then set the ``JWT_secret`` to at least 32 characters
 (more is better up to 512 bits).
 https://sourceforge.net/p/roundup/mailman/ for directions on
 subscribing and for archives of the lists.
 Creating Custom Rate Limits
-===========================
+---------------------------
 You can replace the default rate limiter that is configured using
 the tracker's ``config.ini``. You can return different rate
 limits based on the user, time of day, phase of moon, request
 method (via self.client.request.command) etc.
 function.  This new function uses values for the number of calls
 and period that are specific to a user.  If either is set to 0,
 the defaults from ``config.ini`` file are used.
 Test Examples
-^^^^^^^^^^^^^
+~~~~~~~~~~~~~
 Rate limit tests::
 seq 1 300 | xargs -P 20 -n 1 curl --head -u user:password -si \
 https://.../rest/data/status/new | grep Remaining

Mercurial > p > roundup > code

comparison doc/rest.txt @ 7473:f8b5b0310f88