REST documentation modifications, added keywords, typos, missing link…

…s, added some additional endpoint texts and samples
Evolveum · Feb 27, 2024 · 4860b44 · 4860b44
1 parent 3511a9f
commit 4860b44
Show file tree

Hide file tree

Showing 49 changed files with 586 additions and 221 deletions.
diff --git a/docs/interfaces/midpoint-client-java/index.adoc b/docs/interfaces/midpoint-client-java/index.adoc
@@ -155,7 +155,11 @@ T invokeGet(operation) {
 
 === Object References
 
-TODO: redirects (e.g. add user)
+When a new object is created, the post operation it-self gets a response with an empty body. Yet amongst
+the header information we can find the *Location* header. From this we are capable of constructing the
+reference for the newly created object.
+
+The object reference itself can be then used to fetch the object via a get operation.
 
 [source,java]
 ----
@@ -164,9 +168,6 @@ String newUserOid = newUserRef.getOid();
 UserType newUser = newUserRef.get();  // This may invoke remote GET operation
 ----
 
-TODO: redirects (e.g. add user)
-
-
 === Asynchronous Operations and Redirects
 
 There are synchronous and asynchronous operations in the library interface:

diff --git a/docs/interfaces/rest/concepts/authentication.adoc b/docs/interfaces/rest/concepts/authentication.adoc
@@ -21,19 +21,14 @@ MidPoint REST interface support standard HTTP basic authentication (RFC2617).
 Digest authentication is not supported.
 
 Username and password should correspond to the username and password of appropriately privileged midPoint user.
-For example, the default ones are:
-
-Username: *administrator*
-
-Password: *5ecr3t*
 
 == Proxy (Impersonation)
 
 There are use cases when the authenticated user is not the user which is supposed to execute the operations in midPoint.
 For example a self-service application would like to use the identity of the end user to execute the operations in midPoint.
-However in that case the self-service application would need to know the password of end user.
+However, in that case the self-service application would need to know the password of end user.
 This approach is neither practical nor secure.
-Therefore this use case is supported by other methods.
+Therefore, this use case is supported by other methods.
 The recommended approach is to use a single sign-on (SSO) or similar system to pass end-user identity to midPoint.
 OAuth2 is a recommended approach in the case of midPoint REST interface (see below).
 However, there are cases when OAuth cannot be used.
@@ -42,7 +37,7 @@ The proxy (impersonation) functionality is designed to handle those cases.
 The _proxy_ or _impersonation_ is an ability for one user to switch his identity to different user.
 In the case of self-service application it works like this:
 
-. Setup: Self-service application will be issues with the application credentials.
+. Setup: Self-service application will be issued with the application credentials.
 There will be an application user in midPoint (e.g. `selfserviceapp` user).
 The user will have a strong password which is known to the self-service application.
 
@@ -64,7 +59,7 @@ This header refers to the identity of the end user (`jack`).
 
 . MidPoint will check whether the authenticated (application) user has proxy authorization that allows switch to the end user.
 
-. If the authorization check is successful midPoint will switch the authenticated identity to the use user (`jack`). The operation will be executed using the authorizations of the end user.
+. If the authorization check is successful midPoint will switch the authenticated identity to the user (`jack`). The operation will be executed using the authorizations of the end user.
 The identity of the end user will be recorded in the audit trail.
 
 HTTP header format and example
@@ -76,7 +71,8 @@ Curl example:
 
 [source,bash]
 ----
-curl --user "administrator:5ecr3t" -X GET -H "Switch-To-Principal: dc12980b-0b92-4c4b-9a4d-f18f70ac977f" -H "Accept: application/yaml" "http://localhost:8080/midpoint/ws/rest/self" -v
+# 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
 ----
 
 Example proxy authorization (which is assigned to the application user such as selfserviceapp) :

diff --git a/docs/interfaces/rest/concepts/index.adoc b/docs/interfaces/rest/concepts/index.adoc
@@ -4,12 +4,12 @@
 
 == Description
 
-=== Approach
-
 MidPoint "REST API" is an HTTP-based application programming interface.
 This interface is a set of web resources that provide access to internal midPoint functionality.
 
-[TIP]
+=== Approach
+
+[NOTE]
 .Terminology note
 ====
 We call this interface "REST API" even though it is in fact not entirely RESTful.
@@ -24,8 +24,20 @@ Yes, we should not call this interface "REST".
 But almost everyone else does call things like this "REST", and almost everyone expects to see a "REST" interface, so please excuse us.
 ====
 
-== See Also
+Basic concepts of the interface are described here:
 
 - xref:/midpoint/reference/interfaces/rest/concepts/methods-http-and-outcome/[Use of HTTP Verbs]
 - xref:/midpoint/reference/interfaces/rest/concepts/media-types-rest/[Supported Media Types]
 - xref:/midpoint/reference/interfaces/rest/concepts/authentication/[Authentication]
+
+For the Supported Endpoints and Operations please have a look here:
+
+- xref:/midpoint/reference/interfaces/rest/operations[Operations]
+- xref:/midpoint/reference/interfaces/rest/concepts/endpoints/[REST Endpoints]
+
+
+== See Also
+
+- xref:/midpoint/reference/interfaces/rest/[REST API]
+- xref:/midpoint/reference/interfaces/midpoint-client-java/[MidPoint Client]
+- xref:/midpoint/reference/interfaces/rest/operations/examples/[User Story Examples]
diff --git a/docs/interfaces/rest/endpoints/access-certification-campaign-type.adoc b/docs/interfaces/rest/endpoints/access-certification-campaign-type.adoc
@@ -2,6 +2,7 @@
 :page-nav-title: Access Certification Campaign
 :page-display-order: 900
 :page-toc: top
+:page-keywords: [ 'rest', 'certification', 'campaign' ,'endpoint' ]
 
 == Description
 
@@ -17,11 +18,6 @@ accessCertificationCampaigns/
 == Operations And Examples
 
 The Access Certification Campaign Type endpoint operations and examples.
-// === Create Access Certification Campaign Type Object
-//
-// include::../operations/examples/raw/create-acc.adoc[]
-//
-// - xref:/midpoint/reference/interfaces/rest/operations/create-op-rest/[Create Operation]
 
 === Get Access Certification Campaign Type Objects
 

diff --git a/docs/interfaces/rest/endpoints/access-certification-definition-type.adoc b/docs/interfaces/rest/endpoints/access-certification-definition-type.adoc
@@ -2,7 +2,7 @@
 :page-nav-title: Access Certification Definition
 :page-display-order: 1000
 :page-toc: top
-
+:page-keywords: [ 'rest', 'certification', 'definition' ,'endpoint' ]
 
 == Description
 

diff --git a/docs/interfaces/rest/endpoints/archetypes.adoc b/docs/interfaces/rest/endpoints/archetypes.adoc
@@ -2,6 +2,7 @@
 :page-nav-title: Archetype
 :page-display-order: 1200
 :page-toc: top
+:page-keywords: [ 'rest', 'archetype' ,'endpoint' ]
 
 == Description
 

diff --git a/docs/interfaces/rest/endpoints/cases.adoc b/docs/interfaces/rest/endpoints/cases.adoc
@@ -2,6 +2,7 @@
 :page-nav-title: Case
 :page-display-order: 1300
 :page-toc: top
+:page-keywords: [ 'rest', 'case' ,'endpoint' ]
 
 == Description
 
@@ -17,11 +18,6 @@ cases/
 == Operations And Examples
 
 The Cases endpoint operations and examples.
-// === Create Case Objects
-// // todo ?
-// include::../operations/examples/raw/create-case-assign-employee.adoc[]
-//
-// - xref:/midpoint/reference/interfaces/rest/operations/create-op-rest/[Create Operation]
 
 === Get Case Objects
 

diff --git a/docs/interfaces/rest/endpoints/connector-hosts.adoc b/docs/interfaces/rest/endpoints/connector-hosts.adoc
@@ -2,6 +2,7 @@
 :page-nav-title: Connector Host
 :page-display-order: 1400
 :page-toc: top
+:page-keywords: [ 'rest', 'connector', 'host', 'endpoint' ]
 
 == Description
 

diff --git a/docs/interfaces/rest/endpoints/connectors.adoc b/docs/interfaces/rest/endpoints/connectors.adoc
@@ -2,6 +2,7 @@
 :page-nav-title: Connector
 :page-display-order: 1500
 :page-toc: top
+:page-keywords: [ 'rest', 'connector' ,'endpoint' ]
 
 == Description
 
@@ -14,7 +15,6 @@ Connector objects are a part of the REST API web resources.accessCertificationDe
 connectors/
 ----
 
-
 == Operations And Examples
 
 The Connector Type endpoint operations and examples.

diff --git a/docs/interfaces/rest/endpoints/dashboards.adoc b/docs/interfaces/rest/endpoints/dashboards.adoc
@@ -2,6 +2,7 @@
 :page-nav-title: Dashboard
 :page-display-order: 1600
 :page-toc: top
+:page-keywords: [ 'rest', 'dashboard' ,'endpoint' ]
 
 == Description
 

diff --git a/docs/interfaces/rest/endpoints/forms.adoc b/docs/interfaces/rest/endpoints/forms.adoc
@@ -2,6 +2,7 @@
 :page-nav-title: Form
 :page-display-order: 1700
 :page-toc: top
+:page-keywords: [ 'rest', 'form' ,'endpoint' ]
 
 == Description
 

diff --git a/docs/interfaces/rest/endpoints/functions.adoc b/docs/interfaces/rest/endpoints/functions.adoc
@@ -2,6 +2,7 @@
 :page-nav-title: Function Library
 :page-display-order: 1800
 :page-toc: top
+:page-keywords: [ 'rest', 'function', 'library','endpoint' ]
 
 == Description
 

diff --git a/docs/interfaces/rest/endpoints/generic-objects.adoc b/docs/interfaces/rest/endpoints/generic-objects.adoc
@@ -2,6 +2,7 @@
 :page-nav-title: Generic Object
 :page-display-order: 1900
 :page-toc: top
+:page-keywords: [ 'rest', 'generic' ,'endpoint' ]
 
 == Description
 

diff --git a/docs/interfaces/rest/endpoints/lookup-tables.adoc b/docs/interfaces/rest/endpoints/lookup-tables.adoc
@@ -2,6 +2,7 @@
 :page-nav-title: Lookup Table
 :page-display-order: 2100
 :page-toc: top
+:page-keywords: [ 'rest', 'lookup', 'endpoint' ]
 
 == Description
 
@@ -14,7 +15,6 @@ Lookup Table objects are a part of the REST API web resources.
 lookupTables/
 ----
 
-
 == Operations And Examples
 
 The Lookup Table type endpoint operations and examples.

diff --git a/docs/interfaces/rest/endpoints/misc.adoc b/docs/interfaces/rest/endpoints/misc.adoc
diff --git a/docs/interfaces/rest/endpoints/nodes.adoc b/docs/interfaces/rest/endpoints/nodes.adoc
@@ -2,20 +2,44 @@
 :page-nav-title: Node
 :page-display-order: 2300
 :page-toc: top
+:page-keywords: [ 'rest', 'node', 'endpoint' ]
 
 == Description
 
 Here we are describing the Node object type in relation to midPoints REST API. The
 Node objects are a part of the REST API web resources.
 
-== Applicable Operations
+== Operations And Examples
 
-The Node Type 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.
+The Node type endpoint operations and examples.
 
-// TODO Try this out, I think Only read should be permitted here !?
+=== Get Node type Objects
 
--- TODO
+Get operation for fetching a single specific object.
+
+- xref:/midpoint/reference/interfaces/rest/operations/get-op-rest/[Get Operation]
+
+=== Search for Node type Objects
+
+Search operation usable for fetching the full list of objects or a list based on filter.
+
+include::../operations/examples/raw/search-all.adoc[]
+
+- xref:/midpoint/reference/interfaces/rest/operations/search-op-rest/[Search Operation]
+
+=== Modify Node type Objects
+
+- xref:/midpoint/reference/interfaces/rest/operations/modify-op-rest/[Modify Operation]
+
+=== Delete Node type Objects
+
+- xref:/midpoint/reference/interfaces/rest/operations/delete-op-rest/[Delete Operation]
+
+=== Generate and Validate Operations for Node Objects
+
+Operations to generate or validate values.
+
+- xref:/midpoint/reference/interfaces/rest/operations/generate-and-validate-concrete-op-rest/[Generate and Validate Operations]
 
 == JSON Example
 
@@ -25,9 +49,39 @@ of the output, yet it was removed for the purpose of the example.
 .Show JSON Example
 [%collapsible]
 ====
-[source, http]
+[source, json]
 ----
-
+{
+  "node" : {
+    "oid" : "",
+    "version" : "",
+    "name" : "DefaultNode",
+    "nodeIdentifier" : "DefaultNode",
+    "hostname" : "",
+    "url" : "",
+    "ipAddress" : [  ],
+    "lastCheckInTime" : "",
+    "operationalState" : "up",
+    "clustered" : false,
+    "internalNodeIdentifier" : "",
+    "build" : {
+      "version" : "4.8",
+      "revision" : "v4.8"
+    },
+    "secret" : {},
+    "secretUpdateTimestamp" : "",
+    "taskExecutionLimitations" : {
+      "groupLimitation" : [ {
+        "groupName" : ""
+      }, {
+        "groupName" : "DefaultNode"
+      }, {
+        "groupName" : "*",
+        "limit" : 0
+      } ]
+    }
+  }
+}
 ----
 ====