Merge branch 'docs/cleanup-4.8' into support-4.8

docs/interfaces/rest/concepts/index.adoc

@@ -1,5 +1,5 @@
-= REST API Concepts
-:page-nav-title: REST API Concepts
+= API Concepts
+:page-nav-title: API Concepts
 :page-display-order: 100
 
 == Description

docs/interfaces/rest/operations/examples/raw/create-ou-projects.adoc

@@ -0,0 +1,32 @@
+:page-visibility: hidden
+
+.Create a new Organizational Unit object in MidPoint with file data source
+[source,bash]
+----
+# Authenticating with the credentials "administrator" and password "y0uR_P455woR*d" on a localhost instance running on port 8080
+curl --user administrator:y0uR_P455woR*d -H "Content-Type: application/json" -X POST http://localhost:8080/midpoint/ws/rest/orgs --data-binary @pathToMidpointGit\samples\rest\org-project.json -v
+----
+
+.*Show* data source example for *"Create a new Organizational Unit object in MidPoint"* | link:https://raw.githubusercontent.com/Evolveum/midpoint-samples/master/samples/rest/org-project.json[GitHub]
+[%collapsible]
+====
+[source, json]
+----
+{
+  "org": {
+    "name": "P0000",
+    "displayName": "Projects"
+  }
+}
+----
+====
+
+The response is an HTTP 201 code in case of success *without* a response body.
+Also, the response contains a *Location Header* pointing to the location of the created
+user.
+
+.Example location header
+[source, bash]
+----
+ #Location: http://localhost:8080/midpoint/ws/rest/orgs/e5ae2f30-141c-4990-8387-4c8e7433132d
+----

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

@@ -0,0 +1,9 @@
+:page-visibility: hidden
+.Delete an Organizational Unit type object
+[source,bash]
+----
+# Authenticating with the credentials "administrator" and password "y0uR_P455woR*d" on a localhost instance running on port 8080
+curl --user administrator:y0uR_P455woR*d -X DELETE http://localhost:8080/midpoint/ws/rest/orgs/e5ae2f30-141c-4990-8387-4c8e7433132d -v
+----
+
+The response is an HTTP 204 code in case of success *without* a response body.

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

@@ -1,5 +1,5 @@
 :page-visibility: hidden
-.Delete a User type object
+.Delete a Role type object
 [source,bash]
 ----
 # Authenticating with the credentials "administrator" and password "y0uR_P455woR*d" on a localhost instance running on port 8080

docs/interfaces/rest/operations/examples/raw/get-direct-indirect-assignments.adoc

@@ -0,0 +1,172 @@
+= Get Users Data with Direct and Indirect assignments
+:page-nav-title: Get user based on his unique identificator
+:page-display-order: 200
+:page-toc: top
+:page-keywords: [ 'direct and indirect assignments', 'rest', 'get']
+
+== Description
+Example of retrieving identity data from a web resource object representing a user.
+
+In this case the User is a member of multiple roles by having them either directly
+or indirectly (inducement) assigned.
+
+In our example we want to fetch the data with an emphasis on the active
+assignments (or inducement).
+
+The motivation is to have as much information about
+the assigned objects from this single API call as possible. For this we augment
+the request URI with a special parameter
+
+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.
+
+.Authentication methods used to work with the REST api
+xref:/midpoint/reference/interfaces/rest/concepts/authentication/#_basic_authentication[Authentication methods]
+
+== Example
+
+Notice the usage of the options parameter set to *"resolveNames"*. It lets midPoint
+return an output which additionally to the traditional OID also contains the name of an assigned object.
+
+Look for the *"targetName"* parameter in the output of the request.
+
+[#_get_direct_indirect_assign]
+.Get user with direct and indirect assignments
+
+[source,bash]
+----
+# Authenticating with the credentials "administrator" and password "y0uR_P455woR*d" on a localhost instance running on port 8080
+curl --user administrator:y0uR_P455woR*d -H "Accept: application/json" -X GET http://localhost:8080/midpoint/ws/rest/users/00000000-0000-0000-0000-000000000002?options=resolveNames -v
+----
+
+.Example Output for "Get user with direct and indirect assignments"
+[%collapsible]
+====
+This is only an example output, some *parts* of which *were* either *removed*
+or shortened to emphasize the parts related to the use-case.
+
+Please also notice the sections labeled as *"provenance"*. The *"segmentOrder"* parameter represents
+the order of the assignment in the assignment path (in case of induced assignments).
+
+[source, json]
+----
+{
+  "user" : {
+    "oid" : "a9885c61-c442-42d8-af34-8182a8653e3c",
+    "version" : "",
+    "name" : "Jack",
+    "metadata" : {},
+    "operationExecution" : [ {}, {} ],
+    "assignment" : [ {}, {} ],
+    "iteration" : 0,
+    "iterationToken" : "",
+    "roleMembershipRef" : [ {
+      "@metadata" : {
+        "storage" : {},
+        "provenance" : {
+          "assignmentPath" : {
+            "sourceRef" : {
+              "oid" : "a9885c61-c442-42d8-af34-8182a8653e3c",
+              "relation" : "org:default",
+              "type" : "c:UserType"
+            },
+            "segment" : {
+              "segmentOrder" : 1,
+              "assignmentId" : 2,
+              "targetRef" : {
+                "oid" : "00000000-0000-0000-0000-000000000008",
+                "relation" : "org:default",
+                "type" : "c:RoleType"
+              },
+              "matchingOrder" : true
+            }
+          }
+        }
+      },
+      "oid" : "00000000-0000-0000-0000-000000000008",
+      "relation" : "org:default",
+      "type" : "c:RoleType",
+      "targetName" : "End user"
+    }, {
+      "@metadata" : {
+        "storage" : {},
+        "provenance" : {
+          "assignmentPath" : {
+            "sourceRef" : {
+              "oid" : "a9885c61-c442-42d8-af34-8182a8653e3c",
+              "relation" : "org:default",
+              "type" : "c:UserType"
+            },
+            "segment" : {
+              "segmentOrder" : 1,
+              "assignmentId" : 7,
+              "targetRef" : {
+                "oid" : "c32093b9-a400-42d4-ab7d-5fdd78f96e58",
+                "relation" : "org:default",
+                "type" : "c:RoleType"
+              },
+              "matchingOrder" : true
+            }
+          }
+        }
+      },
+      "oid" : "c32093b9-a400-42d4-ab7d-5fdd78f96e58",
+      "relation" : "org:default",
+      "type" : "c:RoleType",
+      "targetName" : "Java Developer"
+    }, {
+      "@metadata" : {
+        "storage" : {},
+        "provenance" : {
+          "assignmentPath" : {
+            "sourceRef" : {
+              "oid" : "a9885c61-c442-42d8-af34-8182a8653e3c",
+              "relation" : "org:default",
+              "type" : "c:UserType"
+            },
+            "segment" : [ {
+              "segmentOrder" : 1,
+              "assignmentId" : 7,
+              "targetRef" : {
+                "oid" : "c32093b9-a400-42d4-ab7d-5fdd78f96e58",
+                "relation" : "org:default",
+                "type" : "c:RoleType"
+              },
+              "matchingOrder" : true
+            }, {
+              "segmentOrder" : 2,
+              "inducementId" : 2,
+              "targetRef" : {
+                "oid" : "06e34591-a2cd-4b13-a023-74d9db91352c",
+                "relation" : "org:default",
+                "type" : "c:RoleType"
+              },
+              "matchingOrder" : true
+            } ]
+          }
+        }
+      },
+      "oid" : "06e34591-a2cd-4b13-a023-74d9db91352c",
+      "relation" : "org:default",
+      "type" : "c:RoleType",
+      "targetName" : "Developer"
+    } ],
+    "activation" : {},
+    "credentials" : {}
+  }
+}
+----
+====
+
+.Search for users and fetch direct and indirect assignments
+
+[source,bash]
+----
+# Authenticating with the credentials "administrator" and password "y0uR_P455woR*d" on a localhost instance running on port 8080
+curl --user administrator:y0uR_P455woR*d -H "Accept: application/json" -H "Content-Type: application/json" -X POST http://localhost:8080/midpoint/ws/rest/users/search?options=resolveNames --data-binary @pathToMidpointGit\samples\rest\query-all.json -v
+----
+
+== See Also
+
+- xref:/midpoint/reference/interfaces/rest/concepts/media-types-rest/[Supported Media Types]
+- xref:/midpoint/reference/interfaces/rest/concepts/authentication/[Authentication]

docs/interfaces/rest/operations/examples/raw/get-ou-projects.adoc

@@ -0,0 +1,31 @@
+:page-visibility: hidden
+[source,bash]
+----
+# Authenticating with the credentials "administrator" and password "y0uR_P455woR*d" on a localhost instance running on port 8080
+curl --user administrator:y0uR_P455woR*d -H "Accept: application/json" -X GET http://localhost:8080/midpoint/ws/rest/orgs/e5ae2f30-141c-4990-8387-4c8e7433132d?options=raw -v
+----
+
+The response is an HTTP 200 code in case of success with a response body containing the queried item.
+
+.Example Output of *"Get Organizational Unit"* example
+[%collapsible]
+====
+The example is *simplified*, some properties were removed to keep the example output "short". This example *does
+not* contain all possible properties of this object type.
+[source, json]
+----
+{
+  "org" : {
+    "oid" : "e5ae2f30-141c-4990-8387-4c8e7433132d",
+    "version" : "1",
+    "name" : "P0000",
+    "metadata" : {},
+    "operationExecution" : {},
+    "iteration" : 0,
+    "iterationToken" : "",
+    "activation" : {},
+    "displayName" : "Projects"
+  }
+}
+----
+====

docs/interfaces/rest/operations/examples/raw/index.adoc

@@ -0,0 +1 @@
+:page-visibility: hidden

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

@@ -0,0 +1,6 @@
+:page-visibility: hidden
+[source,bash]
+----
+# Authenticating with the credentials "administrator" and password "y0uR_P455woR*d" on a localhost instance running on port 8080
+curl --user administrator:y0uR_P455woR*d -H "Content-Type: application/json" -X PATCH http://localhost:8080/midpoint/ws/rest/orgs/e5ae2f30-141c-4990-8387-4c8e7433132d --data-binary @pathToMidpointGit\samples\rest\modify-attribute-gen.json
+----

docs/interfaces/rest/operations/examples/raw/org-id-generate.adoc

@@ -0,0 +1,7 @@
+:page-visibility: hidden
+.Generate identifier for Role type object
+[source,bash]
+----
+# Authenticating with the credentials "administrator" and password "y0uR_P455woR*d" on a localhost instance running on port 8080
+ curl --user administrator:y0uR_P455woR*d -H "Accept: application/json" -H "Content-Type: application/json" -X POST http://localhost:8080/midpoint/ws/rest/orgs/e5ae2f30-141c-4990-8387-4c8e7433132d/generate --data-binary @pathToMidpointGit\samples\rest\policy-items-identifier-generate.json -v
+----

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

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

docs/interfaces/rest/operations/get-op-rest.adoc

@@ -76,18 +76,16 @@ request.
 
 Example of usage of options:
 
-//TODO full example
-[source, http]
-----
-?options=raw
-----
-
 The *"get"* operations support specifying options influencing the operation execution. You can find the
 supported options in these references:
 
 .Usable options for this type of operation
 link:https://github.com/Evolveum/midpoint/blob/731e408905650d81ecab410f1f1c4f07a0d8795c/infra/schema/src/main/java/com/evolveum/midpoint/schema/GetOperationOptions.java[GetOperationOptionsType]
 
+include::../../rest/operations/raw/options-usage.adoc[]
+
+include::../../rest/operations/raw/operation-prop-search.adoc[]
+
 include::../../rest/concepts/raw/outcome.adoc[]
 
 The response is a set of identity data describing the fetched object. This example

docs/interfaces/rest/operations/raw/index.adoc

@@ -0,0 +1 @@
+:page-visibility: hidden

docs/interfaces/rest/operations/raw/operation-prop-search.adoc

@@ -0,0 +1,16 @@
+:page-visibility: hidden
+
+*Usage of Exclude*
+
+To exclude an attribute in the output of your request, you can specify
+the "exclude" parameter in your query request. The attribute which is
+mentioned after the equals sign will be excluded. In case of excluding
+multiple attributes, specify each exclude with an "&" character after each
+other.
+
+*Example*:
+
+[source,bash]
+----
+?exclude=metadata&exclude=credentials/password/value
+----

docs/interfaces/rest/operations/raw/options-usage.adoc

@@ -0,0 +1,16 @@
+:page-visibility: hidden
+*Usage of Operation Options*
+
+To use a boolean based operation option with your request, append a question
+mark "?" to the original request URI, then type in the "option=" string
+after which you append the name of the option to be used.
+
+Options can be chained with the "&" character if you want to
+use multiple options in your request.
+
+*Example*:
+
+[source,bash]
+----
+?options=raw&options=resolveNames
+----

docs/interfaces/rest/operations/search-op-rest.adoc

@@ -13,6 +13,17 @@
 
 === Options
 
+The *"Search"* operations support specifying options influencing the operation execution. You can find the
+supported options in these references:
+
+.Usable options for this type of operation
+link:https://github.com/Evolveum/midpoint/blob/731e408905650d81ecab410f1f1c4f07a0d8795c/infra/schema/src/main/java/com/evolveum/midpoint/schema/GetOperationOptions.java[GetOperationOptionsType]
+
+include::../../rest/operations/raw/options-usage.adoc[]
+
+include::../../rest/operations/raw/operation-prop-search.adoc[]
+
+
 include::../../rest/concepts/raw/outcome.adoc[]
 
 == Examples

docs/interfaces/rest/resource-types/index.adoc

@@ -1,5 +1,5 @@
 = REST Endpoints
-:page-nav-title: REST Endpoint
+:page-nav-title: REST Endpoints
 :page-display-order: 100
 :page-toc: top