REST documentation changes, UserType Section and main examples

docs/interfaces/rest/operations/examples/raw/create-user-jack.adoc

@@ -1,3 +1,5 @@
+:page-visibility: hidden
+
 .Create a new User object in MidPoint with file data source
 [source,bash]
 ----

docs/interfaces/rest/operations/examples/raw/curl-authenticatoin-intro-note.adoc

@@ -1,3 +1,4 @@
+:page-visibility: hidden
 For the purpose of the sample we are using the CURL tool as it is a well maintained, well
 tested, and it's widely accessible.
 

docs/interfaces/rest/operations/examples/raw/delete-user.adoc

@@ -0,0 +1,9 @@
+:page-visibility: hidden
+.Delete a User type object
+[source,bash]
+----
+# Authenticating with the credentials "administrator" and password "5ecr3t" on a localhost instance running on port 8080
+curl --user administrator:5ecr3t -X DELETE http://localhost:8080/midpoint/ws/rest/users/e4b0c81e-7fc7-462d-a92c-b3e0b10b8b49 -v
+----
+
+The response is an HTTP 204 code in case of success *without* a response body.

docs/interfaces/rest/operations/examples/raw/get-user-administrator.adoc

@@ -1,3 +1,4 @@
+:page-visibility: hidden
 [source,bash]
 ----
 # Authenticating with the credentials "administrator" and password "5ecr3t" on a localhost instance running on port 8080

docs/interfaces/rest/operations/examples/raw/modify-attr-user.adoc

@@ -0,0 +1,6 @@
+:page-visibility: hidden
+[source,bash]
+----
+# Authenticating with the credentials "administrator" and password "5ecr3t" on a localhost instance running on port 8080
+curl --user administrator:5ecr3t -H "Content-Type: application/json" -X PATCH http://localhost:8080/midpoint/ws/rest/users/00000000-0000-0000-0000-000000000002 --data-binary @pathToMidpointGit\samples\rest\modify-attribute-gen.json
+----

docs/interfaces/rest/operations/examples/raw/modify-attr.adoc

@@ -0,0 +1,20 @@
+:page-visibility: hidden
+.*Show* data source example for *"Modify attribute value"* | link:https://raw.githubusercontent.com/Evolveum/midpoint-samples/master/samples/rest/modify-attribute-gen.json[GitHub]
+[%collapsible]
+====
+[source, json]
+----
+{
+	"objectModification": {
+		"itemDelta": {
+			"modificationType": "add",
+			"path": "description",
+			"value": "Description parameter modified via REST"
+		}
+	}
+}
+----
+====
+
+The response is an HTTP 204 code in case of success *without* a response body.
+

docs/interfaces/rest/operations/examples/raw/modify-user-assign-role.adoc

@@ -0,0 +1,44 @@
+:page-visibility: hidden
+.Create a new User object in MidPoint with file data source
+[source,bash]
+----
+# Authenticating with the credentials "administrator" and password "5ecr3t" on a localhost instance running on port 8080
+curl --user administrator:5ecr3t -H "Content-Type: application/xml" -X PATCH http://localhost:8080/midpoint/ws/rest/users/00000000-0000-0000-0000-000000000002 --data-binary @pathToMidpointGit\samples\rest\modify-user-assign-role-eu.xml
+----
+
+.*Show* data source example for *"Create a new User object in MidPoint"* | link:https://raw.githubusercontent.com/Evolveum/midpoint-samples/master/samples/rest/modify-user-assign-role-eu.xml[GitHub]
+[%collapsible]
+====
+[source, xml]
+----
+<?xml version="1.0"?>
+<!--
+  ~ Copyright (c) 2010-2024 Evolveum
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~      http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+<objectModification
+    xmlns='http://midpoint.evolveum.com/xml/ns/public/common/api-types-3'
+    xmlns:c='http://midpoint.evolveum.com/xml/ns/public/common/common-3'
+    xmlns:t="http://prism.evolveum.com/xml/ns/public/types-3">
+    <itemDelta>
+        <t:modificationType>add</t:modificationType>
+        <t:path>c:assignment</t:path>
+        <t:value>
+                <c:targetRef oid="00000000-0000-0000-0000-000000000008" type="c:RoleType" />
+        </t:value>
+    </itemDelta>
+</objectModification>
+
+----
+====

docs/interfaces/rest/operations/examples/raw/search-all-users.adoc

@@ -0,0 +1,7 @@
+:page-visibility: hidden
+.Search for all users
+[source,bash]
+----
+# Authenticating with the credentials "administrator" and password "5ecr3t" on a localhost instance running on port 8080
+curl --user administrator:5ecr3t -H "Accept: application/json" -H "Content-Type: application/json" -X POST http://localhost:8080/midpoint/ws/rest/users/search --data-binary @pathToMidpointGit\samples\rest\query-all.json -v
+----

docs/interfaces/rest/operations/examples/raw/search-all.adoc

@@ -0,0 +1,72 @@
+:page-visibility: hidden
+.*Show* data source example for *"Search for all"* | link:https://raw.githubusercontent.com/Evolveum/midpoint-samples/master/samples/rest/query-all.json[GitHub]
+[%collapsible]
+====
+[source, json]
+----
+{
+  "query" : ""
+}
+----
+====
+
+The response is an HTTP 200 code in case of success with a response body containing the queried items.
+
+.Example Output is a list of objects.
+[%collapsible]
+====
+[source, json]
+----
+{
+  "@ns" : "http://prism.evolveum.com/xml/ns/public/types-3",
+  "object" : {
+    "@type" : "http://midpoint.evolveum.com/xml/ns/public/common/api-types-3#ObjectListType",
+    "object" : [ {
+      "@type" : "",
+      "oid" : "",
+      "version" : "",
+      "name" : "",
+      "metadata" : {
+        "requestTimestamp" : "",
+        "requestorRef" : {
+          "oid" : "",
+          "relation" : "",
+          "type" : ""
+        },
+        "createTimestamp" : "",
+        "creatorRef" : {
+          "oid" : "",
+          "relation" : "",
+          "type" : ""
+        },
+        "createChannel" : ""
+      },
+      "iteration" : ,
+      "iterationToken" : ""
+    }, {
+      "@type" : "",
+      "oid" : "",
+      "version" : "",
+      "name" : "",
+      "metadata" : {
+        "requestTimestamp" : "",
+        "requestorRef" : {
+          "oid" : "",
+          "relation" : "",
+          "type" : ""
+        },
+        "createTimestamp" : "",
+        "creatorRef" : {
+          "oid" : "",
+          "relation" : "",
+          "type" : ""
+        },
+        "createChannel" : ""
+      },
+      "iteration" : ,
+      "iterationToken" : ""
+    } ]
+  }
+}
+----
+====

docs/interfaces/rest/operations/examples/raw/user-pwd-generate.adoc

@@ -0,0 +1,50 @@
+:page-visibility: hidden
+.Generate a password for user
+[source,bash]
+----
+# Authenticating with the credentials "administrator" and password "5ecr3t" on a localhost instance running on port 8080
+ curl --user administrator:5ecr3t -H "Accept: application/json" -H "Content-Type: application/json" -X POST http://localhost:8080/midpoint/ws/rest/users/e297a878-89da-43fa-b67a-d0316975388a/generate --data-binary @pathToMidpointGit\samples\rest\policy-items-password-generate.json
+----
+
+.*Show* data source example for *"Generate a password for user"* | link:https://raw.githubusercontent.com/Evolveum/midpoint-samples/master/samples/rest/policy-items-password-generate.json[GitHub]
+[%collapsible]
+====
+[source, json]
+----
+{
+	"policyItemsDefinition": {
+		"policyItemDefinition": {
+			"target": {
+				"path": "credentials/password/value"
+			},
+			"execute": "true"
+		}
+	}
+}
+----
+====
+The response is an HTTP 200 code in case of success with a response body.
+
+.*Show* example output for *"Generate a password for user"*
+[%collapsible]
+====
+[source, json]
+----
+{
+  "@ns" : "http://prism.evolveum.com/xml/ns/public/types-3",
+  "object" : {
+    "@type" : "http://midpoint.evolveum.com/xml/ns/public/common/api-types-3#PolicyItemsDefinitionType",
+    "policyItemDefinition" : [ {
+      "target" : {
+        "path" : "credentials/password/value"
+      },
+      "value" : {
+        "@type" : "xsd:string",
+        "@value" : "afruD"
+      },
+      "execute" : true
+    } ]
+  }
+}
+----
+====

docs/interfaces/rest/operations/examples/raw/user-pwd-reset.adoc

@@ -0,0 +1,49 @@
+:page-visibility: hidden
+[NOTE]
+====
+This example also needs a configuration change in the system global security policy. You have to enable
+the password reset feature in you configuration, please see xref:/midpoint/reference/security/credentials/password-reset#_pwd_reset_rest_api[this]
+page.
+====
+
+.Execute password reset for user
+[source,bash]
+----
+# Authenticating with the credentials "administrator" and password "5ecr3t" on a localhost instance running on port 8080
+curl --user administrator:5ecr3t -H "Accept: application/json" -H "Content-Type: application/json" -X POST http://localhost:8080/midpoint/ws/rest/users/e297a878-89da-43fa-b67a-d0316975388a/credential --data-binary @pathToMidpointGit\samples\rest\user-pwd-reset.json
+----
+
+.*Show* data source example for *"Execute password reset for user"* | link:https://raw.githubusercontent.com/Evolveum/midpoint-samples/master/samples/rest/user-pwd-reset.json[GitHub]
+[%collapsible]
+====
+[source, json]
+----
+{
+  "executeCredentialResetRequest": {
+    "resetMethod": "passwordReset",
+    "userEntry": "5ecr3tP4s5w0rd"
+  }
+}
+----
+====
+The response is an HTTP 200 code in case of success with a response body.
+
+.*Show* example output for *"Execute password reset for user"*
+[%collapsible]
+====
+[source, json]
+----
+{
+  "@ns" : "http://prism.evolveum.com/xml/ns/public/types-3",
+  "object" : {
+    "@type" : "http://midpoint.evolveum.com/xml/ns/public/common/api-types-3#ExecuteCredentialResetResponseType",
+    "message" : {
+      "@type" : "c:SingleLocalizableMessageType",
+      "key" : "execute.reset.credential.successful",
+      "fallbackMessage" : "Reset password was successful"
+    }
+  }
+}
+
+----
+====

docs/interfaces/rest/operations/examples/user-pwd-reset.adoc

@@ -0,0 +1,14 @@
+= Password Reset Issued by REST request
+:page-nav-title: REST Password Reset
+:page-display-order: 600
+:page-toc: top
+
+== Description
+
+Example of Password reset with the use of the REST interface. The password is provided
+inside the request body.
+
+For the purpose of the sample we are using the CURL tool as it is a well maintained, well
+tested, and it's widely accessible.
+
+include::../examples/raw/user-pwd-reset.adoc[]