Mercurial > p > roundup > code
comparison doc/rest.txt @ 8218:32aaf5dc562b
fix(REST): issue2551383; improve errors for bad json, fix PUT docs
While adding fuzz testing for email addresses via REST
/rest/data/user/1/address, I had an error when setting the address to
the same value it currently had. Traced this to a bug in
userauditor.py. Fixed the bug. Documented in upgrading.txt.
While trying to track down issue, I realized invalid json was being
accepted without error. So I fixed the code that parses the json and
have it return an error. Also modified some tests that broke (used
invalid json, or passed body (e.g. DELETE) but shouldn't have. Add
tests for bad json to verify new code.
Fixed test that wasn't initializing the body_file in each loop, so the
test wasn't actually supplying a body.
Also realised PUT documentation was not correct. Output format isn't
quite like GET.
Fuss tests for email address also added.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Tue, 17 Dec 2024 19:42:46 -0500 |
| parents | 79b9343794f5 |
| children | 11ebd3a19c9a |
comparison
equal
deleted
inserted
replaced
| 8217:cd76d5d59c37 | 8218:32aaf5dc562b |
|---|---|
| 1390 | 1390 |
| 1391 Other Supported Methods for Items | 1391 Other Supported Methods for Items |
| 1392 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 1392 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1393 | 1393 |
| 1394 The method ``PUT`` is allowed on individual items, e.g. | 1394 The method ``PUT`` is allowed on individual items, e.g. |
| 1395 ``/data/issue/42`` On success it returns the same parameters as the | 1395 ``/data/issue/42`` On success it returns a data structure similar to |
| 1396 respective ``GET`` method. Note that for ``PUT`` an Etag has to be | 1396 the respective ``GET`` method. However it is only concerned with the |
| 1397 supplied, either in the request header or as an @etag parameter. An | 1397 changes that have occurred. Since it is not a full ``GET`` request, it |
| 1398 example:: | 1398 doesn't include an etag or unchanged attributes. Note that for ``PUT`` |
| 1399 an Etag has to be supplied, either in the request header or as an | |
| 1400 @etag parameter. An example:: | |
| 1399 | 1401 |
| 1400 curl -u admin:admin -X PUT \ | 1402 curl -u admin:admin -X PUT \ |
| 1401 --header 'Referer: https://example.com/demo/' \ | 1403 --header 'Referer: https://example.com/demo/' \ |
| 1402 --header 'X-Requested-With: rest' \ | 1404 --header 'X-Requested-With: rest' \ |
| 1403 --header "Content-Type: application/json" \ | 1405 --header "Content-Type: application/json" \ |
| 1613 Other Supported Methods for fields | 1615 Other Supported Methods for fields |
| 1614 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 1616 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1615 | 1617 |
| 1616 The method ``PUT`` is allowed on a property e.g., | 1618 The method ``PUT`` is allowed on a property e.g., |
| 1617 ``/data/issue/42/title``. On success it returns the same parameters as | 1619 ``/data/issue/42/title``. On success it returns the same parameters as |
| 1618 the respective ``GET`` method. Note that for ``PUT`` an Etag has to be | 1620 the respective ``PUT`` method on the item. For example:: |
| 1621 | |
| 1622 { | |
| 1623 "data": { | |
| 1624 "id": "42", | |
| 1625 "type": "issue", | |
| 1626 "link": "https://.../demo/rest/data/issue/42", | |
| 1627 "attribute": { | |
| 1628 "title": "this is a new title" | |
| 1629 } | |
| 1630 } | |
| 1631 } | |
| 1632 | |
| 1633 If the new value for the title was the same as on the server, the | |
| 1634 attribute property would be empty since the value was not changed. | |
| 1635 Note that for ``PUT`` an Etag has to be | |
| 1619 supplied, either in the request header or as an @etag parameter. | 1636 supplied, either in the request header or as an @etag parameter. |
| 1620 Example using multipart/form-data rather than json:: | 1637 Example using multipart/form-data rather than json:: |
| 1621 | 1638 |
| 1622 curl -vs -u provisional:provisional -X PUT \ | 1639 curl -vs -u provisional:provisional -X PUT \ |
| 1623 --header "Accept: application/json" \ | 1640 --header "Accept: application/json" \ |
| 2436 seq 1 300 | xargs -P 20 -n 1 curl --head -u user:password -si \ | 2453 seq 1 300 | xargs -P 20 -n 1 curl --head -u user:password -si \ |
| 2437 https://.../rest/data/status/new | grep Remaining | 2454 https://.../rest/data/status/new | grep Remaining |
| 2438 | 2455 |
| 2439 will show you the number of remaining requests to the REST interface | 2456 will show you the number of remaining requests to the REST interface |
| 2440 for the user identified by password. | 2457 for the user identified by password. |
| 2458 | |
| 2459 | |
| 2460 Notes V2 API | |
| 2461 ~~~~~~~~~~~~ | |
| 2462 | |
| 2463 These may never be implemented but, some nits to consider. | |
| 2464 | |
| 2465 The shape of a GET and PUT/PATCH responses are different. "attributes" | |
| 2466 is used for GET and "attribute" is used with PATCH/PUT. A PATCH or a | |
| 2467 PUT can update multiple properties when used with an item endpoint. | |
| 2468 "attribute" kind of makes sense when used with a property endpoint | |
| 2469 but.... Maybe standardize on one shape so the client doesn't have to | |
| 2470 special case? |