diff --git a/README.rst b/README.rst index 555f654346..b45848649a 100644 --- a/README.rst +++ b/README.rst @@ -112,7 +112,7 @@ If you are having issues, please let us know via the `issue tracker `_ (Germany) -- `4teamwork `_ (Switzerland) +- `4teamwork `_ (Switzerland) - `CodeSyntax `_ (Spain) diff --git a/docs/source/endpoints/users.md b/docs/source/endpoints/users.md index 7a63ea90e7..ced6498dfc 100644 --- a/docs/source/endpoints/users.md +++ b/docs/source/endpoints/users.md @@ -12,6 +12,7 @@ myst: Available users in a Plone site can be created, queried, updated, and deleted by interacting with the `/@users` endpoint on portal root. This action requires an authenticated user: + ## List Users To retrieve a list of all current users in the portal, call the `/@users` endpoint with a `GET` request: @@ -55,6 +56,7 @@ The server will return a {term}`401 Unauthorized` status code. :language: http ``` + ### Filtering the list of users The endpoint supports some basic filtering. @@ -88,6 +90,7 @@ The server will respond with a list of users where the users are member of one o The endpoint also takes a `limit` parameter. Its default is a maximum of 25 users at a time for performance reasons. + ### Search users Search by `id`, `fullname` and `email`: @@ -103,6 +106,7 @@ The server will respond with a list of users where the `fullname`, `email` or `i :language: http ``` + ## Create User To create a new user, send a `POST` request to the global `/@users` endpoint with a JSON representation of the user you want to create in the body: @@ -129,6 +133,7 @@ The `Location` header contains the URL of the newly created user, and the resour If no roles have been specified, then a `Member` role is added as a sensible default. + ## Read User To retrieve all details for a particular user, send a `GET` request to the `/@users` endpoint and append the user ID to the URL: @@ -185,6 +190,7 @@ In this case, the server will respond with a {term}`200 OK` status code and the :language: http ``` + ## Update User To update the settings of a user, send a `PATCH` request with the user details you want to amend to the URL of that particular user. @@ -229,6 +235,7 @@ If you still want Plone to take care of image scaling using the default Plone be :request: ../../../src/plone/restapi/tests/http-examples/users_update_portrait_scale.req ``` + ## Delete User To delete a user, send a `DELETE` request to the `/@users` endpoint and append the user ID of the user you want to delete. @@ -245,13 +252,14 @@ A successful response will be indicated by a {term}`204 No Content` response: :language: http ``` -When deleting a user in large sites with a lot of users and content the deleting operation may take a lot of time to the extent of setting it in an unresponsive state. +When deleting a user in large sites with a lot of users and content, the `delete` operation may take a lot of time to the extent that the site enters an unresponsive state. -There is a workaround about this which is to request Plone not to delete the Member areas or the local roles that may have been granted in the past. +There is a workaround for this. +You may request Plone not to delete the member areas or the local roles that may have been granted in the past. -To mark such a behavior we need to pass specific parameters to the delete endpoint. +To mark such a behavior, we need to pass specific parameters to the `delete` endpoint. -In this case we request not to delete the local roles: +In this case, we request not to delete the local roles: ```{eval-rst} .. http:example:: curl httpie python-requests @@ -282,11 +290,12 @@ Both parameters can be added in the same request. ```{warning} These two specific requests should be made with special care because they may leave traces of the deleted users in the Plone database. -Specifically, although the user is deleted the reference of its permissions stay on the database. +Specifically, although the user is deleted, the reference of its permissions stay in the database. -This means that if in the future you add a new user with the same userid, it may get the local roles and member area previously created for the old user. +This means that if in the future you add a new user with the same `userid`, it may get the local roles and member area previously created for the old user. ``` + ## User registration Plone allows you to enable user self registration. @@ -309,6 +318,7 @@ If the user has been created, the server will respond with a {term}`201 Created` :language: http ``` + ## Reset User Password Plone allows to reset a password for a user by sending a `POST` request to the user resource and appending `/reset-password` to the URL: @@ -328,6 +338,7 @@ The token that is part of the reset URL in the email can be used to authorize se :request: ../../../src/plone/restapi/tests/http-examples/users_reset.req ``` + ### Reset Own Password Plone also allows a user to reset her own password directly without sending an email. @@ -351,6 +362,7 @@ To set the password with the old password, you need either the `Set own password If an API consumer tries to send a password in the payload that is not the same as the currently logged in user, the server will respond with a {term}`400 Bad Request` response. + ### Return Values - {term}`200 OK` diff --git a/docs/source/upgrade-guide.md b/docs/source/upgrade-guide.md index c839355141..a9b5953710 100644 --- a/docs/source/upgrade-guide.md +++ b/docs/source/upgrade-guide.md @@ -13,6 +13,14 @@ This upgrade guide lists all breaking changes in `plone.restapi`. It explains the steps that are needed to upgrade to the latest version. +## Upgrading to `plone.restapi` 8.x + +`plone.restapi` 8.x dropped support for Python 2 and Plone 5.1 and 4.3. +Upgrading to `plone.restapi` 8.x does not require any changes to your code base if you use Python 3 and Plone 5.2 or newer. + +If you use Python 2 and a Plone version older than 5.2, stick with `plone.restapi` 7.x. + + ## Upgrading to `plone.restapi` 7.x The navigation endpoint has been refactored. @@ -394,11 +402,11 @@ New response: { "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes", "items": [ - { - "title": "Collection", - "token": "Collection" - }, - "…" + { + "title": "Collection", + "token": "Collection" + }, + "…" ], "items_total": 12 } @@ -729,7 +737,7 @@ Pull Request: Use top level `@navigation` and `@breadcrumb` endpoints instead. [timo] - Remove `sharing` attributes from `GET` response. [timo, jaroel] - Convert `richtext` using `.output_relative_to`. - Direct conversion from `RichText` is no longer supported as we *always* need a context for the `ITransformer`. [jaroel] + Direct conversion from `RichText` is no longer supported as we _always_ need a context for the `ITransformer`. [jaroel] ### Remove @components endpoint @@ -799,7 +807,7 @@ Use `.output_relative_to` to convert `richtext`. Changelog: - Convert `richtext` using `.output_relative_to.` - Direct conversion from `RichText` is no longer supported as we *always* need a context for the `ITransformer`. [jaroel] + Direct conversion from `RichText` is no longer supported as we _always_ need a context for the `ITransformer`. [jaroel] Pull Request: diff --git a/news/1691.documentation b/news/1691.documentation new file mode 100644 index 0000000000..4f4b00f45a --- /dev/null +++ b/news/1691.documentation @@ -0,0 +1 @@ +Restores formatting and fixes some MyST syntax from #1689. @stevepiercy diff --git a/news/1692.documentation b/news/1692.documentation new file mode 100644 index 0000000000..0575be1495 --- /dev/null +++ b/news/1692.documentation @@ -0,0 +1 @@ +Documentation fixes for #1599. @stevepiercy diff --git a/news/1693.documentation b/news/1693.documentation new file mode 100644 index 0000000000..631f576982 --- /dev/null +++ b/news/1693.documentation @@ -0,0 +1 @@ +Fix linkcheckbroken 301 redirect to https://www.4teamwork.ch/en. @stevepiercy