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:
Stay tuned, operation is in progress.
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 consistency mechanism.
In this two cases, midPoint returns the OperationResult where there details of executed operations can be found.
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.
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 OperationResult structure is usually provided in the response to provide more details about the situation.
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 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).