REST docu updates, adding a couple missing indec pages, updating OP p…

…ages and examples
Evolveum · Jan 12, 2024 · 1372d31 · 1372d31
1 parent 0f600fb
commit 1372d31
Show file tree

Hide file tree

Showing 9 changed files with 256 additions and 230 deletions.
diff --git a/docs/interfaces/rest/concepts/methods-http-and-outcome.adoc b/docs/interfaces/rest/concepts/methods-http-and-outcome.adoc
@@ -153,227 +153,5 @@ Status codes and the indication of errors and asynchronous processing applies un
 
 // TODO refactoring this to specific example chapters
 
-=== Supported operations
 
-The base URL of REST API is link:http://localhost:8080/midpoint/ws/rest[http://localhost:8080/midpoint/ws/rest] (alternatively to */ws/rest* paths */api/model* and */rest/model* are also supported).
 
-* Use the base URL + path from the table below to request concrete operation.
-
-
-* Supply the \{type} with the specific type of object you want to add (or modify, delete, [.line-through]#search#, etc).
-Supported types are listed in Table 1 above.
-
-* Supply the \{oid} with the specific oid of your object.
-
-* Some operations support specifying options influencing the operation execution, e.g. if the execution is made in raw mode, or the shadows are not fetched from the resource, etc.
-*Supported options* column shows supported options for different operations.
-To specify option, use query parameters, e.g. http://localhots:8080/midpoint/api/model/users*?options=raw*
-
-[%autowidth]
-|===
-| Operation name | Operation type | Path | Supported options | Data | Response
-
-| Create new object
-| POST
-| /\{type}
-| link:https://evolveum.com/downloads/midpoint/latest/midpoint-latest-schemadoc/http---midpoint-evolveum-com-xml-ns-public-common-common-3/type/ModelExecuteOptionsType.html[ModelExecuteOptionsType]
-| Object to create in the XML form
-a| * 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
-
-
-| Create or update object
-| PUT
-| /\{type}/\{oid}
-| link:https://evolveum.com/downloads/midpoint/latest/midpoint-latest-schemadoc/http---midpoint-evolveum-com-xml-ns-public-common-common-3/type/ModelExecuteOptionsType.html[ModelExecuteOptionsType]
-| Object to create in the XML form
-a| * 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
-
-
-| Get object
-| GET
-| /\{type}/\{oid}
-| link:https://github.com/Evolveum/midpoint/blob/731e408905650d81ecab410f1f1c4f07a0d8795c/infra/schema/src/main/java/com/evolveum/midpoint/schema/GetOperationOptions.java[GetOperationOptionsType]
-| -
-a| * 200 OK, current object in the response body
-
-
-| Modify object
-| PATCH, POST
-| /\{type}/\{oid}
-| link:https://evolveum.com/downloads/midpoint/latest/midpoint-latest-schemadoc/http---midpoint-evolveum-com-xml-ns-public-common-common-3/type/ModelExecuteOptionsType.html[ModelExecuteOptionsType]
-| Modifications in XML format
-a| * 204 No Content
-* 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
-
-
-| Delete object
-| DELETE
-| /\{type}/\{oid}
-| link:https://evolveum.com/downloads/midpoint/latest/midpoint-latest-schemadoc/http---midpoint-evolveum-com-xml-ns-public-common-common-3/type/ModelExecuteOptionsType.html[ModelExecuteOptionsType]
-| -
-a| * 204 No Content
-* 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
-
-
-| Test (configured) Resource
-| POST
-| /resources/\{oid}/test
-| No
-| -
-a| * 200 OK, result of the test operation in the body
-
-
-| Import from Resource
-| POST
-| /resources/\{oid}/import/\{objectClass}
-| No
-| -
-a| * 303 See Other, Location set to point to the concrete "import" task
-
-
-| Find owner of shadow
-| GET
-| /shadows/\{oid}/owner
-| No
-| -
-a| * 200 OK, owner of the shadow returned in the response body
-
-
-| Import shadow
-| POST
-| /shadows/\{oid}/import
-| No
-| -
-a| * 200 OK, result of the import operation in the body
-
-
-| Search
-| POST
-| /\{type}/search
-| link:https://github.com/Evolveum/midpoint/blob/731e408905650d81ecab410f1f1c4f07a0d8795c/infra/schema/src/main/java/com/evolveum/midpoint/schema/GetOperationOptions.java[GetOperationOptionsType]
-| xref:/midpoint/reference/concepts/query/[Query] in XML format
-a| * 200 OK, list of found objects in the body
-
-
-| Suspend tasks
-| POST
-| /tasks/\{oid}/suspend
-| No
-| -
-a| * 204 No Content
-
-
-| Resume tasks
-| POST
-| /tasks/\{oid}/resume
-| No
-| -
-a| * 202 Accepted
-
-
-| Schedule task now
-| POST
-| /tasks/\{oid}/run
-| No
-| -
-a| * 202 Accepted
-
-
-| Notify change
-| POST
-| /notifyChange
-| No
-| Resource object shadow change description
-a| * 200 OK
-
-
-| Generate value for concrete object
-| POST
-| /\{type}/\{oid}/generate
-| No
-| Policy for items describing how to generate the value (PolicyItemsDefinitionType)
-a| * 200 OK
-* 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
-
-
-| Generate value
-| POST
-| /rpc/generate
-| No
-| PolicyItemsDefinitionType
-a| * 200 OK
-* 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
-
-
-| Validate value for concrete object
-| POST
-| /\{type}/\{oid}/validate
-| No
-| PolicyItemsDefinitionType
-a| * 200 OK
-* 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
-
-
-| Validate value
-| POST
-| /rpc/validate
-| No
-| PolicyItemsDefinitionType
-a| * 200 OK
-* 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
-
-
-| Get user's value policy
-| GET
-| /users/\{oid}/policy
-| No
-|
-a| * 200 OK, value policy for user in the response body
-
-
-| Get 'self'
-| GET
-| /self
-| No
-|
-a| * 200 OK, current object in the response body
-
-
-| Search objects by type
-| GET
-| /\{type}
-| link:https://github.com/Evolveum/midpoint/blob/731e408905650d81ecab410f1f1c4f07a0d8795c/infra/schema/src/main/java/com/evolveum/midpoint/schema/GetOperationOptions.java[GetOperationOptionsType]
-|
-a| * 200 OK, list of object of specified type in the response body
-
-
-| Reset credentials
-| POST
-| /users/\{oid}/credential
-| No
-| ExecuteCredentialResetRequestType - specify reset method and new password
-a| * 200 OK, ExecuteCredentialResetResponseType returned in the body.
-
-
-
-| Execute script
-| POST
-| /rpc/executeScript
-| No
-| ExecuteScriptType
-a| * 200 OK, ExecuteScriptResponseType returned in the body
-* 201 Created, Location set to point to the newly created Task object. Only applicable is asynchronous=true parameter is used.
-* 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
-
-|===
diff --git a/docs/interfaces/rest/index.adoc b/docs/interfaces/rest/index.adoc
@@ -60,7 +60,7 @@ The most *basic form* of the url request would be:
 .Request to read own profile data (raw)
 [source,http]
 ----
-GET http://localhost:8080/midpoint/ws/rest/self?raw=true
+GET http://localhost:8080/midpoint/ws/rest/self?options=raw
 ----
 .Request to read own profile data (raw) full example using CURL
 xref:/midpoint/reference/interfaces/rest/operations/examples/get-user-self/#_ex_get_own_profile_information_json_raw[Request to

diff --git a/docs/interfaces/rest/operations/create-op-rest.adoc b/docs/interfaces/rest/operations/create-op-rest.adoc
@@ -60,7 +60,7 @@ Example of usage of options:
 //TODO full example
 [source, http]
 ----
-?raw=true
+?options=raw
 ----
 
 In case of create with the use of the *PUT* method please have a look at the folowing

diff --git a/docs/interfaces/rest/operations/examples/create-object.adoc b/docs/interfaces/rest/operations/examples/create-object.adoc
@@ -1,6 +1,6 @@
 = Create object
 :page-nav-title: REST API Create object
-:page-display-order: 300
+:page-display-order: 400
 :page-toc: top
 
 == Description

diff --git a/docs/interfaces/rest/operations/examples/get-user-self.adoc b/docs/interfaces/rest/operations/examples/get-user-self.adoc
@@ -1,6 +1,6 @@
 = Get User Self
 :page-nav-title: REST API Get User Self
-:page-display-order: 200
+:page-display-order: 300
 :page-toc: top
 
 == Description
@@ -32,7 +32,7 @@ curl --user administrator:5ecr3t -H "Accept: application/json" -X GET http://loc
 .Get Own profile information 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/self?raw=true
+curl --user administrator:5ecr3t -H "Accept: application/json" -X GET http://localhost:8080/midpoint/ws/rest/self?options=raw
 ----
 
 == See Also

diff --git a/docs/interfaces/rest/operations/examples/get-user-unique-id.adoc b/docs/interfaces/rest/operations/examples/get-user-unique-id.adoc
@@ -1,6 +1,6 @@
 = Get User Based on His Unique Identificator
 :page-nav-title: REST API Get user based on his unique identificator
-:page-display-order: 100
+:page-display-order: 200
 :page-toc: top
 
 == Description
@@ -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?raw=true
+curl --user administrator:5ecr3t -H "Accept: application/json" -X GET http://localhost:8080/midpoint/ws/rest/users/00000000-0000-0000-0000-000000000002?options=raw
 ----
 
 == See Also

diff --git a/docs/interfaces/rest/operations/examples/index.adoc b/docs/interfaces/rest/operations/examples/index.adoc
@@ -0,0 +1,14 @@
+= REST examples
+:page-nav-title: REST API Examples
+:page-display-order: 100
+:page-toc: top
+
+== Description
+Common use-cases and user story examples for the midPoint REST API.
+
+Please have a look on the child pages of this document.
+
+== See Also
+
+- xref:/midpoint/reference/interfaces/rest/concepts/media-types-rest/[Supported Media Types]
+- xref:/midpoint/reference/interfaces/rest/concepts/media-types-rest/[Authentication]
diff --git a/docs/interfaces/rest/operations/get-op-rest.adoc b/docs/interfaces/rest/operations/get-op-rest.adoc
@@ -79,7 +79,7 @@ Example of usage of options:
 //TODO full example
 [source, http]
 ----
-?raw=true
+?options=raw
 ----
 
 The *"get"* operations support specifying options influencing the operation execution. You can find the