Mercurial > p > roundup > code
comparison doc/rest.txt @ 6638:e1588ae185dc issue2550923_computed_property
merge from default branch. Fix travis.ci so CI builds don't error out
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Thu, 21 Apr 2022 16:54:17 -0400 |
| parents | 0351caa802f7 |
| children | ff8845ca305e |
comparison
equal
deleted
inserted
replaced
| 6508:85db90cc1705 | 6638:e1588ae185dc |
|---|---|
| 1 .. meta:: | |
| 2 :description language=en: | |
| 3 Documentation on the RESTful interface to the Roundup Issue | |
| 4 Tracker. | |
| 5 | |
| 6 | |
| 1 .. index:: pair: api; Representational state transfer | 7 .. index:: pair: api; Representational state transfer |
| 2 pair: api; rest | 8 pair: api; rest |
| 3 | 9 |
| 4 ==================== | 10 ==================== |
| 5 REST API for Roundup | 11 REST API for Roundup |
| 225 | 231 |
| 226 Performing a ``GET`` on an item or property of an item will return an | 232 Performing a ``GET`` on an item or property of an item will return an |
| 227 ETag header or an @etag property. This needs to be submitted with | 233 ETag header or an @etag property. This needs to be submitted with |
| 228 ``DELETE``, ``PUT`` and ``PATCH`` operations on the item using an | 234 ``DELETE``, ``PUT`` and ``PATCH`` operations on the item using an |
| 229 ``If-Match`` header or an ``"@etag`` property in the data payload if | 235 ``If-Match`` header or an ``"@etag`` property in the data payload if |
| 230 the method supports a payload. | 236 the method supports a payload. The ETag header value will include a |
| 237 suffix (starting with '-') indicating the Content-Encoding used to | |
| 238 respond to the request. If the response was uncompressed, there will | |
| 239 be no suffix. The ``@etag`` property never includes the suffix. Any | |
| 240 ETag value suffixed or not can be sent in an ``If-Match`` header as | |
| 241 the suffix is ignored during comparison. | |
| 231 | 242 |
| 232 The exact details of returned data is determined by the value of the | 243 The exact details of returned data is determined by the value of the |
| 233 ``@verbose`` query parameter. The various supported values and their | 244 ``@verbose`` query parameter. The various supported values and their |
| 234 effects are described in the following sections. | 245 effects are described in the following sections. |
| 235 | 246 |
| 706 To retreive the content, you can use the content link property: | 717 To retreive the content, you can use the content link property: |
| 707 ``https://.../demo/msg11/``. The trailing / is required. Without the | 718 ``https://.../demo/msg11/``. The trailing / is required. Without the |
| 708 /, you get a web page that includes metadata about the message. With | 719 /, you get a web page that includes metadata about the message. With |
| 709 the slash you get a text/plain (in most cases) data stream. | 720 the slash you get a text/plain (in most cases) data stream. |
| 710 | 721 |
| 711 Also you can use the url: | 722 Also you can use the url: ``https://.../demo/rest/data/msg/11?@verbose=3`` |
| 712 | |
| 713 and the content property (if the data is utf-8 compatible) now looks | 723 and the content property (if the data is utf-8 compatible) now looks |
| 714 like:: | 724 like:: |
| 715 | 725 |
| 716 ... | 726 ... |
| 717 "author": { | 727 "author": { |
| 1855 | 1865 |
| 1856 class RestfulInstance(object): | 1866 class RestfulInstance(object): |
| 1857 @Routing.route("/jwt/issue", 'POST') | 1867 @Routing.route("/jwt/issue", 'POST') |
| 1858 @_data_decorator | 1868 @_data_decorator |
| 1859 def generate_jwt(self, input): | 1869 def generate_jwt(self, input): |
| 1870 """Create a JSON Web Token (jwt) | |
| 1871 """ | |
| 1860 import jwt | 1872 import jwt |
| 1861 import datetime | 1873 import datetime |
| 1862 from roundup.anypy.strings import b2s | 1874 from roundup.anypy.strings import b2s |
| 1863 | 1875 |
| 1864 # require basic auth to generate a token | 1876 # require basic auth to generate a token |
| 1877 if scheme.lower() != 'basic': | 1889 if scheme.lower() != 'basic': |
| 1878 raise Unauthorised(denialmsg) | 1890 raise Unauthorised(denialmsg) |
| 1879 else: | 1891 else: |
| 1880 raise Unauthorised(denialmsg) | 1892 raise Unauthorised(denialmsg) |
| 1881 | 1893 |
| 1894 # verify we have input data. | |
| 1895 if not input: | |
| 1896 raise UsageError("Missing data payload. " | |
| 1897 "Verify Content-Type is sent") | |
| 1898 | |
| 1882 # If we reach this point we have validated that the user has | 1899 # If we reach this point we have validated that the user has |
| 1883 # logged in with a password using basic auth. | 1900 # logged in with a password using basic auth. |
| 1884 all_roles = list(self.db.security.role.items()) | 1901 all_roles = list(self.db.security.role.items()) |
| 1885 rolenames = [] | 1902 rolenames = [] |
| 1886 for role in all_roles: | 1903 for role in all_roles: |
| 1908 if lifetime: # if lifetime = 0 make unlimited by omitting exp claim | 1925 if lifetime: # if lifetime = 0 make unlimited by omitting exp claim |
| 1909 claim['exp'] = datetime.datetime.utcnow() + lifetime | 1926 claim['exp'] = datetime.datetime.utcnow() + lifetime |
| 1910 | 1927 |
| 1911 newroles = [] | 1928 newroles = [] |
| 1912 if 'roles' in input: | 1929 if 'roles' in input: |
| 1913 for role in input['roles'].value: | 1930 for role in [ r.lower() for r in input['roles'].value ]: |
| 1914 if role not in rolenames: | 1931 if role not in rolenames: |
| 1915 raise UsageError("Role %s is not valid."%role) | 1932 raise UsageError("Role %s is not valid."%role) |
| 1916 if role in user_roles: | 1933 if role in user_roles: |
| 1917 newroles.append(role) | 1934 newroles.append(role) |
| 1918 continue | 1935 continue |