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

docs/interfaces/rest/concepts/authentication.adoc

@@ -7,6 +7,7 @@
 :page-wiki-metadata-modify-user: virgo
 :page-wiki-metadata-modify-date: 2020-06-02T10:29:25.618+02:00
 :page-toc: top
+:page-keywords: [ 'rest', 'authentication' ]
 
 [TIP]
 ====
@@ -71,7 +72,6 @@ Curl example:
 
 [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 GET -H "Switch-To-Principal: dc12980b-0b92-4c4b-9a4d-f18f70ac977f" -H "Accept: application/yaml" "http://localhost:8080/midpoint/ws/rest/self" -v
 ----
 
@@ -84,16 +84,13 @@ Example proxy authorization (which is assigned to the application user such as s
   <object>
     <type>UserType</type>
     <filter>
-      <q:equal>
-        <q:path>employeeType</q:path>
-        <q:value>enduser</q:value>
-      </q:equal>
+        <text>archetypeRef/@/name = "Person"</text>
     </filter>
   </object>
 </authorization>
 ----
 
-The authorization above allows the user to switch identity to any other user who has the `employeeType` attribute set to value `enduser`.
+The authorization above allows the user to switch identity to any other user who has the archetype `person` assigned.
 
 == Security Questions
 
@@ -135,7 +132,7 @@ Example curl call:
 curl -X GET -H "Authorization: SecQ ew0KInVzZXIiIDogImFkbWluaXN0cmF0b3IiLA0KImFuc3dlciIgOiBbDQogew0KICAgInFpZCIgOiAiaHR0cDovL21pZHBvaW50LmV2b2x2ZXVtLmNvbS94bWwvbnMvcHVibGljL3NlY3VyaXR5L3F1ZXN0aW9uLTIjcTAwMSIsDQogICAicWFucyIgOiAiSSBkb24ndCBrbm93ISINCiB9DQpdDQp9" -H "Content-Type: application/xml" -H "Accept: application/yaml" "http://localhost:8080/midpoint/ws/rest/self" -v
 ----
 
-=== challengeResponseSecQ Challenge - Response implementation
+=== Challenge - Response implementation (challengeResponseSecQ)
 
 The whole sequence with link:https://httpie.org/[HTTPie] and link:https://linux.die.net/man/1/base64[base64] encoding using command substitution in bash may look like this:
 

docs/interfaces/rest/concepts/using-rest-examples.adoc

@@ -0,0 +1,160 @@
+= How To Use The REST API Examples
+:page-nav-title: REST API Examples How To
+:page-display-order: 500
+:page-keywords: [ 'rest', 'examples', 'samples' ]
+:page-toc: top
+
+== Introduction
+
+The *REST* API documentation pages contain a large number of *examples*.
+If you are trying to use them for the first time, and you are not familiar with the tools used than you might face some issues, or maybe have some questions.
+This page is dedicated to help you with this.
+
+== Tools
+
+In the examples used through the REST api documentation pages we use the tool link:https://curl.se/[*CURL*] as a web client for issuing the REST requests.
+We use curl because it is a well known, free and open source software.
+It's well documented, and it's supported on many platforms.
+
+Usually you will see something similar to the following format of a curl command in out documentation.
+The example contains both Windows *shell* and *bash* usage, in our examples we will use *bash* as the differences are only in the "new line" escape characters.
+
+[source,bash]
+----
+curl --user administrator:y0uR_P455woR*d \ <1> <2>
+-H "Accept: application/json" \ <3>
+-H "Content-Type: application/json" \ <4>
+-X POST http://localhost:8080/midpoint/ws/rest/users/search \ <5>
+-v \ <6>
+--data-binary @./samples/rest/query-all.json <7>
+----
+[source,shell]
+----
+curl --user administrator:y0uR_P455woR*d ^ <1> <2>
+-H "Accept: application/json" ^ <3>
+-H "Content-Type: application/json" ^ <4>
+-X POST http://localhost:8080/midpoint/ws/rest/users/search ^ <5>
+-v ^ <6>
+--data-binary @./samples/rest/query-all.json <7>
+----
+<1> Invocation of curl
+<2> Authentication with username and password <username:password>
+<3> Reply content type header format
+<4> Response content type header format
+<5> Request with the request method and REST endpoint URI
+<6> Output is more verbose (includes request and response header data and more)
+<7> Data which should be attached to the API request
+
+== Authentication
+
+The midPoint api currently uses only basic username and password authentication. For some more information regarding
+this please see the following documentation link:
+xref:/midpoint/reference/interfaces/rest/concepts/authentication/#_basic_authentication[Authentication methods]
+
+In our REST examples you will quite often see the following:
+[source,bash]
+----
+--user administrator:y0uR_P455woR*d
+----
+
+This part of the curl command means that we authorize the request as done by the user administrator with the password "y0uR_P455woR*d".
+
+== Payload Data
+
+Some operations also are required to contain a data payload.
+The content differs based on the operation or endpoint of the request.
+
+In our examples we use the *--data-binary* parameter to mark the beginning of the payload data.
+We often reference a file on the file system, for this you need to use the *'@'* character.
+
+The *./samples/rest/* directory structure reference is used because we call the sample data from the base directory of our midPoint *samples* project.
+The project can be found on link:https://github.com/Evolveum/midpoint-samples[github].
+
+[source,bash]
+----
+--data-binary @./samples/rest/query-all.json
+----
+
+=== Request Content Type
+
+In case we are using a REST request which contains additional data in its body, we might want to specify the content type which we use.
+
+This can be done by declaring a specific "Content-Type" header.
+[source,bash]
+----
+-H "Content-Type: application/json"
+----
+
+If no header is declared a default "application/xml" is assumed.
+
+Here is a list of the  xref:/midpoint/reference/interfaces/rest/concepts/media-types-rest/[supported *Media Types*].
+
+=== Reply Content Type
+
+The default reply type is "application/xml". If you would like some other type returned byt the request invocation you will have to use another type of header:
+
+The "Accept" header.
+
+[source,bash]
+----
+-H "Accept: application/json"
+----
+
+Similar to the request header, the accept header has the same set of media types provided as the content header.
+
+Here is a list of the  xref:/midpoint/reference/interfaces/rest/concepts/media-types-rest/[supported *Media Types*].
+
+
+== Authorizations
+
+There are two types of authorizations which you need to have configured and assigned to the account executing the request.
+
+The actual interface *access* authorizations (e.g. to access the search objects operation).
+And a *model* authorization.
+
+The model authorization permit or deny specific actions executed in the interface.
+
+=== Access Authorizations
+
+The examples which we use imply the usage of the administrator user. The administrator
+user has the *"superuser"* authorization role assigned by default this permits the user
+complete access to the interface and also model.
+
+Additionally, by accessing each operation page, the documentation contains a more "fine-grained"
+authorization which can be used. For a list of operations please see the following xref:/midpoint/reference/interfaces/rest/operations/[link]
+
+=== Model Authorizations
+
+The examples which we use imply the usage of the administrator user. The administrator
+user has the *"superuser"* authorization role assigned by default this permits the user
+complete access to the interface and also model.
+
+It is good practice to limit the access of users to only specific parts of the interface and
+permit only specific actions, please have a look at this xref:/midpoint/reference/security/authorization/model.adoc[link] for model authorizations.
+
+=== Troubleshooting
+
+==== Frequent Issues
+
+===== Missing '@' Character In Data Content File Path
+
+A request was issued via CURL with the "--data-binary" property set to a filepath pointing to a file.
+The issue is that the '@' character was not appended to the request before the filepath string.
+
+If '@' is appended before a string in the "--data-binary" property value, CURL knows that it should look for a file rather than use the string as a paiload.
+[source,bash]
+----
+--data-binary @./samples/rest/query-all.json
+----
+
+=== Troubleshooting Tips
+
+- An error reply quite often has data in the body.
+- Additionally check midPoint log for further information
+- Unauthorized messages point to lacking authorizations of the user invoking the request
+
+== See Also
+
+- xref:/midpoint/reference/interfaces/rest/concepts/media-types-rest/[Supported Media Types]
+- xref:/midpoint/reference/interfaces/rest/concepts/authentication/[Authentication]
+- xref:/midpoint/reference/security/authorization/service/[]

docs/interfaces/rest/endpoints/access-certification-campaign-type.adoc

@@ -19,6 +19,13 @@ accessCertificationCampaigns/
 
 The Access Certification Campaign Type endpoint operations and examples.
 
+include::../raw/curl-env-note.adoc[]
+
+For some help regarding the REST examples please see this link:
+
+xref:/midpoint/reference/interfaces/rest/concepts/using-rest-examples.adoc[How to use MidPoint REST examples]
+
+
 === Get Access Certification Campaign Type Objects
 
 Get operation for fetching a single specific object.

docs/interfaces/rest/endpoints/access-certification-definition-type.adoc

@@ -18,6 +18,13 @@ accessCertificationDefinitions/
 
 The Access Certification Definition Type endpoint operations and examples.
 
+include::../raw/curl-env-note.adoc[]
+
+For some help regarding the REST examples please see this link:
+
+xref:/midpoint/reference/interfaces/rest/concepts/using-rest-examples.adoc[How to use MidPoint REST examples]
+
+
 === Create Access Certification Definition Type Object
 
 - xref:/midpoint/reference/interfaces/rest/operations/create-op-rest/[Create Operation]

docs/interfaces/rest/endpoints/archetypes.adoc

@@ -19,6 +19,13 @@ archetypes/
 
 The Archetype Type endpoint operations and examples.
 
+include::../raw/curl-env-note.adoc[]
+
+For some help regarding the REST examples please see this link:
+
+xref:/midpoint/reference/interfaces/rest/concepts/using-rest-examples.adoc[How to use MidPoint REST examples]
+
+
 === Create Archetype Type Object
 
 - xref:/midpoint/reference/interfaces/rest/operations/create-op-rest/[Create Operation]

docs/interfaces/rest/endpoints/cases.adoc

@@ -19,6 +19,13 @@ cases/
 
 The Cases endpoint operations and examples.
 
+include::../raw/curl-env-note.adoc[]
+
+For some help regarding the REST examples please see this link:
+
+xref:/midpoint/reference/interfaces/rest/concepts/using-rest-examples.adoc[How to use MidPoint REST examples]
+
+
 === Get Case Objects
 
 Get operation for fetching a single specific object.
@@ -33,7 +40,7 @@ include::../operations/examples/raw/get-case-employee.adoc[]
 
 Search operation usable for fetching the full list of objects or a list based on filter.
 
-include::../operations/examples/raw/search-all-cases.adoc[]
+include::../operations/examples/raw/search-name-cases.adoc[]
 
 - xref:/midpoint/reference/interfaces/rest/operations/search-op-rest/[Search Operation]
 
@@ -56,7 +63,6 @@ include::../operations/examples/raw/delete-case.adoc[]
 - xref:/midpoint/reference/interfaces/rest/operations/generate-and-validate-concrete-op-rest/[Generate and Validate Operations]
 
 == Common Use-case Examples
-1.
 
 == JSON Example
 

docs/interfaces/rest/endpoints/connector-hosts.adoc

@@ -19,6 +19,13 @@ connectorHosts/
 
 The Connector Host Type endpoint operations and examples.
 
+include::../raw/curl-env-note.adoc[]
+
+For some help regarding the REST examples please see this link:
+
+xref:/midpoint/reference/interfaces/rest/concepts/using-rest-examples.adoc[How to use MidPoint REST examples]
+
+
 === Create Connector Host Type Object
 
 - xref:/midpoint/reference/interfaces/rest/operations/create-op-rest/[Create Operation]

docs/interfaces/rest/endpoints/connectors.adoc

@@ -19,6 +19,13 @@ connectors/
 
 The Connector Type endpoint operations and examples.
 
+include::../raw/curl-env-note.adoc[]
+
+For some help regarding the REST examples please see this link:
+
+xref:/midpoint/reference/interfaces/rest/concepts/using-rest-examples.adoc[How to use MidPoint REST examples]
+
+
 === Create Connector Type Object
 
 - xref:/midpoint/reference/interfaces/rest/operations/create-op-rest/[Create Operation]

docs/interfaces/rest/endpoints/dashboards.adoc

@@ -19,6 +19,13 @@ dashboards/
 
 The Dashboard type endpoint operations and examples.
 
+include::../raw/curl-env-note.adoc[]
+
+For some help regarding the REST examples please see this link:
+
+xref:/midpoint/reference/interfaces/rest/concepts/using-rest-examples.adoc[How to use MidPoint REST examples]
+
+
 === Create Dashboard type Object
 
 - xref:/midpoint/reference/interfaces/rest/operations/create-op-rest/[Create Operation]

docs/interfaces/rest/endpoints/forms.adoc

@@ -19,6 +19,13 @@ forms/
 
 The Form Type endpoint operations and examples.
 
+include::../raw/curl-env-note.adoc[]
+
+For some help regarding the REST examples please see this link:
+
+xref:/midpoint/reference/interfaces/rest/concepts/using-rest-examples.adoc[How to use MidPoint REST examples]
+
+
 === Create Form Type Object
 
 - xref:/midpoint/reference/interfaces/rest/operations/create-op-rest/[Create Operation]

docs/interfaces/rest/endpoints/functions.adoc

@@ -19,6 +19,13 @@ functionLibraries/
 
 The Function Library Type endpoint operations and examples.
 
+include::../raw/curl-env-note.adoc[]
+
+For some help regarding the REST examples please see this link:
+
+xref:/midpoint/reference/interfaces/rest/concepts/using-rest-examples.adoc[How to use MidPoint REST examples]
+
+
 === Create Function Library Type Object
 
 - xref:/midpoint/reference/interfaces/rest/operations/create-op-rest/[Create Operation]

docs/interfaces/rest/endpoints/generic-objects.adoc

@@ -19,6 +19,13 @@ genericObjects/
 
 The Generic Object Type endpoint operations and examples.
 
+include::../raw/curl-env-note.adoc[]
+
+For some help regarding the REST examples please see this link:
+
+xref:/midpoint/reference/interfaces/rest/concepts/using-rest-examples.adoc[How to use MidPoint REST examples]
+
+
 === Create Generic Object Type Object
 
 - xref:/midpoint/reference/interfaces/rest/operations/create-op-rest/[Create Operation]

docs/interfaces/rest/endpoints/lookup-tables.adoc

@@ -19,6 +19,13 @@ lookupTables/
 
 The Lookup Table type endpoint operations and examples.
 
+include::../raw/curl-env-note.adoc[]
+
+For some help regarding the REST examples please see this link:
+
+xref:/midpoint/reference/interfaces/rest/concepts/using-rest-examples.adoc[How to use MidPoint REST examples]
+
+
 === Create Lookup Table type Object
 
 - xref:/midpoint/reference/interfaces/rest/operations/create-op-rest/[Create Operation]

docs/interfaces/rest/endpoints/nodes.adoc

@@ -13,6 +13,13 @@ Node objects are a part of the REST API web resources.
 
 The Node type endpoint operations and examples.
 
+include::../raw/curl-env-note.adoc[]
+
+For some help regarding the REST examples please see this link:
+
+xref:/midpoint/reference/interfaces/rest/concepts/using-rest-examples.adoc[How to use MidPoint REST examples]
+
+
 === Get Node type Objects
 
 Get operation for fetching a single specific object.