Merge branch 'docs/cleanup-4.8' of github.com:Evolveum/midpoint into …

…docs/cleanup-4.8

docs/interfaces/rest/authentication.adoc → docs/interfaces/rest/concepts/authentication.adoc

@@ -14,11 +14,19 @@ Starting with 4.2 the REST API uses xref:/midpoint/reference/security/authentica
 SecQ must be added via xref:/midpoint/reference/security/security-policy/[Security Policy Configuration].
 ====
 
+[#_basic_authentication]
 == Basic Authentication
 
 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.

docs/interfaces/rest/concepts/index.adoc

@@ -0,0 +1,31 @@
+= REST API Concepts
+:page-nav-title: REST API Concepts
+:page-display-order: 100
+
+== 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]
+.Terminology note
+====
+We call this interface "REST API" even though it is in fact not entirely RESTful.
+This API is not hypertext-based.
+Hypertext is not intended paradigm for this interface.
+Also, we are not strictly restful in some details.
+E.g. there are combined web resources that perhaps should be modeled as many smaller web resources if we would follow a strict RESTful approach.
+However, that would be painfully inefficient to use.
+There are also some parts that are obviously RPC-based.
+We are doing this to make the API practical as practicality is our highest priority.
+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
+
+- 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]

docs/interfaces/rest/concepts/media-types-rest.adoc

@@ -0,0 +1,30 @@
+= Supported Media Types
+:page-nav-title: Supported Media Types
+:page-display-order: 300
+
+
+== Supported media types
+
+The following formats and related media types are supported:
+
+[%autowidth]
+|===
+| Format | Media type
+
+| XML
+| `application/xml`, `++application/*+xml++`, `text/xml`
+
+
+| JSON
+| `application/json`
+
+
+| YAML
+| `application/yaml`, `application/yml`, `++application/*+yaml++`, `++application/*+yml++`,
+`text/yaml`, `text/yml`, `++text/*+yaml++`, `++text/*+yml++` +
+Note: There is no official registered media type.
+
+
+|===
+
+Some operations return plain text only (`text/plain`).

docs/interfaces/rest/concepts/methods-http-and-outcome.adoc

@@ -0,0 +1,157 @@
+= Usage of HTTP Methods
+:page-nav-title: Usage of HTTP Methods
+:page-display-order: 400
+
+
+== Use of HTTP Verbs
+
+MidPoint REST API tries to adhere to the usual HTTP verbs and tries to maintain their original meaning:
+
+[%autowidth]
+|===
+| Verb | Meaning and usage
+
+| GET
+| Information retrieval.
+Returns the state of the web resource.
+Also used to execute searches.
+
+| PUT
+| Create new web resource.
+This usually means creation of a new object.
+However, the client has to provide a complete object, including the identifier (URI).
+Which is not entirely practical, as this means that the client needs to know how to properly construct the URI.
+Therefore this operation is seldom used.
+
+| POST
+a| POST is used for several purposes:
+
+* Create new web resources without the need to know the URI.
+POST to a collection web resource will result that a new sub-resource is created.
+
+* As an equivalent for PATCH operation (see below).
+Some HTTP clients have problems when using non-standard verbs.
+Therefore we provide POST as an alternative way to modify objects.
+
+* To pass data to an RPC-like operation.
+
+| PATCH
+| Modification of existing web resource.
+Usually modification of existing midPoint object.
+This is non-standard HTTP verb.
+The usage of PATCH is preferred because its meaning is much more clear than the desperately overloaded meaning of POST.
+However, POST is provided as an equivalent to PATCH for HTTP clients that have problems with non-standard verbs.
+
+| DELETE
+| Delete existing resource.
+This is used mostly to delete objects.
+
+|===
+
+
+
+== Creation of New Resources
+
+According to REST architectural style the web resources should be created by PUT operation.
+However, this assumes that the client knows the URI and therefore it is not very practical.
+E.g. URI of most midPoint objects contains xref:/midpoint/devel/prism/concepts/object-identifier/[Object ID], which may or may not be provided by the client.
+In case that the OID is server-generated the PUT operation is out of question.
+But even if the OID is client-generated this would expect that the client knows how to construct a URI, which is not very RESTful.
+Therefore the PUT operation is not very practical.
+
+The usual way how to create a new object in midPoint REST API is to use POST operation to a collection resource.
+E.g. new user is created by posting the user object to "users" collection (`.../ws/rest/users`).
+MidPoint will react by creating a new user object and publishing that as a new web resource (with new URI).
+MidPoint REST API will respond with and redirection HTTP status (3xx) pointing client to the new URI.
+
+== Synchronous and Asynchronous Operations
+
+Most midPoint operations are currently implemented in a synchronous fashion.
+When talking about REST API this means that they will not return HTTP response until they are finished.
+When the operation is finished, midPoint will respond with success (2xx) or error (4xx, 5xx).
+If new resource is created, redirect status (3xx) is indicated.
+Retrieving that resource should result in success (2xx).
+
+There are also some operations that are executed asynchronously.
+In that case midPoint returns HTTP response as soon as the operation is initiated.
+The status in the response will indicate redirection (3xx).
+The redirection target is a xref:/midpoint/architecture/concepts/task/[task] that can be used to track operation progress.
+
+
+== Return Values
+
+GET operations are supposed to return data.
+GET invoked on REST-like resources returns what anyone would probably expect: either individual midPoint object or a collection of midPoint objects.
+All such resources are supposed to behave in the same way, regardless of their type.
+PUT/POST/PATCH/DELETE for those resources also works in the same way.
+It returns HTTP status code or indicates an error or asynchronous operation (see below).
+
+However, the situation is very different for the RPC-like resources.
+The indication of error and asynchronous processing is the same here.
+But all the rest is different.
+Those operations usually take data using the body of a POST request.
+And the data format may be completely different for each operation.
+The output also differs a lot.
+Success/failure is always indicated by the HTTP error code.
+But the data returned on success vary according to the definition of the specific web resource that is used.
+This is quite expected as those are essentially procedure calls.
+
+Operation success and errors are always indicated by the HTTP error code.
+MidPoint REST API maintains the original HTTP meaning of the error code classes:
+
+[%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
+
+
+