Merge remote-tracking branch 'origin/support-4.8' into support-4.8

docs/interfaces/rest/concepts/raw/outcome.adoc

@@ -0,0 +1,58 @@
+=== Response
+
+[%autowidth]
+|===
+| Error code | Meaning
+
+| 1xx
+| Information.
+Stay tuned, operation is in progress.
+
+| 2xx
+a| Success.
+Operation finished successfully.
+There are two custom codes:
+
+* 250 for partial error which means that during processing some error occurred but some changes was executed.
+
+* 240 for handled error which means that there was originally error, but midPoint was able to fix this using its xref:/midpoint/reference/synchronization/consistency/[consistency mechanism.]
+
+In this two cases, midPoint returns the xref:/midpoint/architecture/concepts/operation-result/[OperationResult] where there details of executed operations can be found.
+
+| 3xx
+a| Redirection or "in progress".
+This is returned mostly to indicate two cases:
+
+* Operation has finished, but the results are not in this resource.
+Redirection is issues to point the client to the results.
+Typical example is creation of an object with POST to a collection web resource.
+In this case a new object is created, new URI is assigned and the client is redirected to this URI.
+Retrieving that URI provides created object and 200 status code, indicating that the operation is finished.
+
+* Operation is in progress (asynchronous operation).
+In this case midPoint API redirects the client to a task object that can be used to track progress of the operation.
+
+| 4xx
+| Client errors.
+The client has sent request that cannot be processed.
+This indicates usual situation that are well handled by the midPoint code.
+Maybe the client request to create conflicting object, delete non-existent object, modification that violates the schema and so on.
+The xref:/midpoint/architecture/concepts/operation-result/[OperationResult] structure is usually provided in the response to provide more details about the situation.
+
+
+| 5xx
+| Server errors.
+Situations that the server cannot handle and where the cause is unknown.
+This usually means bugs in the code, insufficient resources such as RAM or disk space, unforeseen failures in the infrastructure and so on.
+The xref:/midpoint/architecture/concepts/operation-result/[OperationResult] structure might or might not be provided in this case.
+Some errors are so severe that the structured error information might not be available.
+
+
+|===
+
+Status codes and the indication of errors and asynchronous processing applies uniformly to all midPoint web resources (both RESTful and RPC).
+
+// TODO refactoring this to specific example chapters
+
+
+

docs/interfaces/rest/index.adoc

@@ -46,17 +46,6 @@ xref:/midpoint/reference/interfaces/rest/concepts/authentication/#_basic_authent
 
 The most *basic form* of the url request would be:
 
-// TODO add full complexity or keep this simple example ???
-
-// [source, http]
-// ----
-// http://localhost:8080/midpoint/ws/rest/{web_resource_type}/{operation}
-// ----
-
-// [source, http]
-// ----
-// xref::/midpoint/reference/interfaces/rest/operations/examples/get-user-self/#_ex_get_own_profile_information[]
-// ----
 .Request to read own profile data (raw)
 [source,http]
 ----
@@ -67,11 +56,19 @@ xref:/midpoint/reference/interfaces/rest/operations/examples/get-user-self/#_ex_
 
 Naturally by having a feature rich interface there is no "one size fits them all" way to invoke the operations, so the url will
 be different in specific use cases. The most common ones you can see
-at xref:/#_common_use_cases[this] section of the documentation.
+at xref:/midpoint/reference/interfaces/rest/#_common_use_cases[this] section of the documentation.
 
 The REST interface provides you with a long list of *web resource types* which you can access. The interface also provides
 you with *different kinds of operations*, based on the type of resource you choose.
 
+.*Commonly Used Web Resource Types:*
+- xref:/midpoint/reference/interfaces/rest/resource-types/users/[users]
+- xref:/midpoint/reference/interfaces/rest/resource-types/roles/[roles]
+- xref:/midpoint/reference/interfaces/rest/resource-types/organizational-units/[orgs]
+- xref:/midpoint/reference/interfaces/rest/resource-types/resources/[resources]
+- xref:/midpoint/reference/interfaces/rest/resource-types/rpc/[rpc]
+
+
 .The *full collection of web resource types* can be found here:
 xref:/midpoint/reference/interfaces/rest/resource-types/[Web Resource Types]
 
@@ -85,12 +82,12 @@ xref:/midpoint/reference/interfaces/midpoint-client-java/[MidPoint Client Librar
 [#_common_use_cases]
 == Common Use Cases
 
--- TODO add links
+// TODO add links
 
 1. List all users with their profile information.
-2. Get user based on his unique identificator (TODO link to OID docu)
-3. Create or update a new user.
-4. Modify the user by assigning an account.
+2. xref:/midpoint/reference/interfaces/rest/operations/examples/get-user-unique-id/[Get User with the REST API]
+3. Create User with the REST API
+4. Assign User Account with the REST API
 
 
 

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

@@ -3,7 +3,7 @@
 :page-display-order: 300
 :page-toc: top
 
-== Description
+== Create With Rest
 Request to create a midPoint object based on data provided in the body of the request.
 
 == Request
@@ -75,14 +75,7 @@ links were you can find the options described:
 .Usable options for this type of operation
 link:https://evolveum.com/downloads/midpoint/latest/midpoint-latest-schemadoc/http---midpoint-evolveum-com-xml-ns-public-common-common-3/type/ModelExecuteOptionsType.html[ModelExecuteOptionsType]
 
-
-=== Response
-
-In case of success you might see the following response codes:
-
--   201 Created, Location set to point to the newly created object
--   240 Handled error, xref:/midpoint/architecture/concepts/operation-result/[OperationResult] is returned in the body
--   250 Partial error, xref:/midpoint/architecture/concepts/operation-result/[OperationResult] is returned in the body
+include::../../rest/concepts/raw/outcome.adoc[]
 
 == Examples
 

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

@@ -3,7 +3,7 @@
 :page-display-order: 400
 :page-toc: top
 
-== Description
+== Delete With Rest
 Request to delete a midPoint object.
 
 == Request
@@ -25,7 +25,7 @@ DELETE http://localhost:8080/midpoint/ws/rest/{web_resource_type}/{oid}
 
 === Options
 
-=== Response
+include::../../rest/concepts/raw/outcome.adoc[]
 
 == Examples
 

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

@@ -0,0 +1,35 @@
+= Create object
+:page-nav-title: Create object
+:page-display-order: 500
+:page-toc: top
+
+== Description
+Example of creating an midPoint object representing some identity data in the
+form of a new User type object
+
+include::../examples/raw/curl-authenticatoin-intro-note.adoc[]
+
+.Authentication methods used to work with the REST api
+xref:/midpoint/reference/interfaces/rest/concepts/authentication/#_basic_authentication[Authentication methods]
+
+== Example
+//TODO
+.Create a new User object in MidPoint with file data source
+[source,bash]
+----
+curl --user administrator:5ecr3t -H "Content-Type: application/xml" -X POST http://localhost:8080/midpoint/ws/rest/users --data-binary @pathToMidpointGit\samples\rest\rest-user.xml -v
+----
+
+.*Show* data source example for *"Create a new User object in MidPoint"
+[%collapsible]
+====
+[source, xml]
+----
+include::https://raw.githubusercontent.com/Evolveum/midpoint-samples/master/samples/rest/user-.xml[]
+----
+====
+
+== 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/get-user-unique-id.adoc

@@ -13,8 +13,8 @@ tested, and it's widely accessible.
 xref:/midpoint/reference/interfaces/rest/concepts/authentication/#_basic_authentication[Authentication methods]
 
 == Example
-
-.Get Object
+[#_get_default_administrator_object]
+.Get default administrator object
 [source,bash]
 ----
 curl --user administrator:5ecr3t -X GET http://localhost:8080/midpoint/ws/rest/users/00000000-0000-0000-0000-000000000002
@@ -29,7 +29,7 @@ curl --user administrator:5ecr3t -H "Accept: application/json" -X GET http://loc
 .Get Object in JSON format with the Raw option set to true
 [source,bash]
 ----
-curl --user administrator:5ecr3t -H "Accept: application/json" -X GET http://localhost:8080/midpoint/ws/rest/users/00000000-0000-0000-0000-000000000002?options=raw
+include::../examples/raw/get-user-administrator.adoc[]
 ----
 
 == See Also

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

@@ -0,0 +1,13 @@
+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.
+
+The body of the request will contain data from an external configuration file,
+the data will be inserted into the request via native Curl commands.
+
+[NOTE]
+====
+If you are using file as a source for the data in the REST call with *curl*, please, don't forget to use '*@*' before the path to your file.
+
+Sometimes the newlines are not correctly handled during the transfer.
+(See bug:MID-5229[].) If that occurs, please use `--data-binary`  instead of `-d`.
+====

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

@@ -0,0 +1 @@
+curl --user administrator:5ecr3t -H "Accept: application/json" -X GET http://localhost:8080/midpoint/ws/rest/users/00000000-0000-0000-0000-000000000002?options=raw

docs/interfaces/rest/operations/generate-and-validate-concrete-op-rest.adoc

@@ -13,7 +13,7 @@
 
 === Options
 
-=== Response
+include::../../rest/concepts/raw/outcome.adoc[]
 
 == Examples
 

docs/interfaces/rest/operations/generate-and-validate-op-rest.adoc

@@ -13,7 +13,7 @@
 
 === Options
 
-=== Response
+include::../../rest/concepts/raw/outcome.adoc[]
 
 == Examples
 

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

@@ -88,7 +88,8 @@ 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]
 
-=== Response
+include::../../rest/concepts/raw/outcome.adoc[]
+
 The response is a set of identity data describing the fetched object. This example
 had some technical information and metadata related to the environment removed before publishing.
 

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

@@ -13,7 +13,7 @@
 
 === Options
 
-=== Response
+include::../../rest/concepts/raw/outcome.adoc[]
 
 == Examples
 

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

@@ -13,7 +13,7 @@
 
 === Options
 
-=== Response
+include::../../rest/concepts/raw/outcome.adoc[]
 
 == Examples
 

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

@@ -13,7 +13,7 @@
 
 === Options
 
-=== Response
+include::../../rest/concepts/raw/outcome.adoc[]
 
 == Examples
 

docs/interfaces/rest/operations/script-execute-op-rest.adoc

@@ -13,7 +13,7 @@
 
 === Options
 
-=== Response
+include::../../rest/concepts/raw/outcome.adoc[]
 
 == Examples
 

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

@@ -13,7 +13,7 @@
 
 === Options
 
-=== Response
+include::../../rest/concepts/raw/outcome.adoc[]
 
 == Examples
 

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

@@ -13,7 +13,7 @@
 
 === Options
 
-=== Response
+include::../../rest/concepts/raw/outcome.adoc[]
 
 == Examples
 

docs/interfaces/rest/operations/task-specific-op-rest.adoc

@@ -13,7 +13,7 @@
 
 === Options
 
-=== Response
+include::../../rest/concepts/raw/outcome.adoc[]
 
 == Examples
 

docs/interfaces/rest/operations/user-specific-op-rest.adoc

@@ -13,7 +13,7 @@
 
 === Options
 
-=== Response
+include::../../rest/concepts/raw/outcome.adoc[]
 
 == Examples
 

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

@@ -3,7 +3,7 @@
 :page-display-order: 200
 :page-toc: top
 
-== Description
+== User Type REST Endpoint
 
 Here we are describing the User object type in relation to midPoints REST API. The
 User objects are a part of the REST API web resources.
@@ -19,7 +19,11 @@ users/
 The User web resource is a part of the Create-Read-Update-Delete (CRUD) web resources
 present in midPoint. This is apparent in the operations which are available for this type of object.
 
-// TODO referencie na operacie
+.Get Default Administrator User with REST
+[source, http]
+----
+include::../operations/examples/raw/get-user-administrator.adoc[]
+----
 
 - xref:/midpoint/reference/interfaces/rest/operations/create-op-rest/[Create Operation]
 - xref:/midpoint/reference/interfaces/rest/operations/get-op-rest/[Get Operation]
@@ -32,8 +36,8 @@ present in midPoint. This is apparent in the operations which are available for
 == Common Use-case Examples
 
 1. xref:/midpoint/reference/interfaces/rest/operations/examples/create-object/[Create object]
-1. xref:/midpoint/reference/interfaces/rest/operations/examples/get-user-unique-id/[Get user based on his unique identificator]
-2. xref:/midpoint/reference/interfaces/rest/operations/examples/get-user-self/[Get own profile information]
+2. xref:/midpoint/reference/interfaces/rest/operations/examples/get-user-unique-id/[Get user based on his unique identificator]
+3. xref:/midpoint/reference/interfaces/rest/operations/examples/get-user-self/[Get own profile information]
 
 
 == JSON Example