Mercurial > p > roundup > code
comparison doc/rest.txt @ 6311:be8d5a8e090a
Fix uncaught error when parsing rest headers, document
Started this work as better docs for rest response format. But I found
406 error response was not being tested. Also there was no error for
bad Content-Type.
In rest.py fix uncaught exceptions due to invalid Accept or
Content-Type headers. If Content-type is valid but not
application/json return code 415.
Document use of accept header (was only shown in examples) and support
for q parameter. Describe using .xml and .json extensions to select
return format for testing from browser (where setting accept header is
a problem). Document 406 error code return. Document 415 error code
return and acceptable content types. Previously only doc was in
examples.
Set up tests for 406 and 415 error codes.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Fri, 01 Jan 2021 14:14:34 -0500 |
| parents | 9d132769ed37 |
| children | 84655a4223c6 |
comparison
equal
deleted
inserted
replaced
| 6310:68d83479747b | 6311:be8d5a8e090a |
|---|---|
| 185 | 185 |
| 186 If an explicit version is not provided, the server default is used. | 186 If an explicit version is not provided, the server default is used. |
| 187 The server default is reported by querying the ``/rest/`` endpoint as | 187 The server default is reported by querying the ``/rest/`` endpoint as |
| 188 described above. | 188 described above. |
| 189 | 189 |
| 190 Input Formats | |
| 191 ============= | |
| 192 | |
| 193 Content-Type is allowed to be ``application/json`` or | |
| 194 ``application/x-www-form-urlencoded``. Any other value returns error | |
| 195 code 415. | |
| 196 | |
| 197 Response Formats | |
| 198 ================ | |
| 199 | |
| 200 The default response format is json. | |
| 201 | |
| 202 If you add the ``dicttoxml.py`` module you can request XML formatted | |
| 203 data using the header ``Accept: application/xml`` in your | |
| 204 request. Both output formats are similar in structure. | |
| 205 | |
| 206 The rest interface accepts the http accept header and can include | |
| 207 ``q`` values to specify the preferred mechanism. This is the preferred | |
| 208 way to specify alternate acceptable response formats. | |
| 209 | |
| 210 To make testing from the browser easier, you can also append the | |
| 211 extension `.json` or `.xml` to the path component of the url. This | |
| 212 will force json or xml (if supported) output. If you use an extension | |
| 213 it takes priority over any accept headers. | |
| 214 | |
| 215 The rest interface returns status 406 if you use an unrecognized | |
| 216 extension. You will also get a 406 status if none of the entries in | |
| 217 the accept header are available or if the accept header is invalid. | |
| 218 | |
| 219 | |
| 190 General Guidelines | 220 General Guidelines |
| 191 ================== | 221 ================== |
| 192 | 222 |
| 193 Performing a ``GET`` on an item or property of an item will return an | 223 Performing a ``GET`` on an item or property of an item will return an |
| 194 ETag header or an @etag property. This needs to be submitted with | 224 ETag header or an @etag property. This needs to be submitted with |
| 198 | 228 |
| 199 The exact details of returned data is determined by the value of the | 229 The exact details of returned data is determined by the value of the |
| 200 ``@verbose`` query parameter. The various supported values and their | 230 ``@verbose`` query parameter. The various supported values and their |
| 201 effects are described in the following sections. | 231 effects are described in the following sections. |
| 202 | 232 |
| 203 The default return format is JSON. If you add the ``dicttoxml.py`` | 233 All output is wrapped in an envelope called ``data``. The output |
| 204 module you can request XML formatted data using the header ``Accept: | 234 format is described in `Response Formats`_ above. |
| 205 application/xml`` in your request. Both output formats are similar in | |
| 206 structure. | |
| 207 | |
| 208 All output is wrapped in an envelope called ``data``. | |
| 209 | 235 |
| 210 When using collection endpoints (think list of issues, users ...), the | 236 When using collection endpoints (think list of issues, users ...), the |
| 211 ``data`` envelope contains metadata (e.g. total number of items) as | 237 ``data`` envelope contains metadata (e.g. total number of items) as |
| 212 well as a ``collections`` list of objects:: | 238 well as a ``collections`` list of objects:: |
| 213 | 239 |