POST http://localhost:8080/midpoint/ws/rest/{endpoint}/searchSearch Operation
Description
As the name implies, the Search operation is used to search for specific objects. This is done with a filter query. In our case we use a query which is specified in the body of the request (rather than a part of the URI itself).
Request
The request itself is an HTTP POST operation. The URI contains the endpoint {endpoint} which should be used in the search and also the /search keyword.
Execute the Search request via HTTP POST
Headers
Regarding authorization type, the "Basic" Authorization header should be used.
Authorization header example replace {Base64EncodedCredentials} with the encoded credentials
Authorization: Basic {Base64EncodedCredentials}To specify the provided content type, please use the "Content-Type" header payload in the body:
Content type header example, other media types are supported as well
"Content-Type: application/json"You might need to specify the accepted type of content in case you are interested in a format different from xml (default):
Accept type header example, other media types are supported as well
"Accept: application/json"For supported media types please refer to the following section of the documentation
Body
The body consists of a Query in the form of a QueryType type of objects. Please see an example in the examples bellow.
Options
The "Search" operations support specifying options influencing the operation execution. You can find the supported options in these references:
Usable options for this type of operation
Usage of Operation Options
To use a boolean based operation option with your request, append a question mark "?" to the original request URI, then type in the "option=" string after which you append the name of the option to be used.
Options can be chained with the "&" character if you want to use multiple options in your request.
Example:
?options=raw&options=resolveNamesUsage of Exclude
To exclude an attribute in the output of your request, you can specify the "exclude" parameter in your query request. The attribute which is mentioned after the equals sign will be excluded. In case of excluding multiple attributes, specify each exclude with an "&" character after each other.
Example:
?exclude=metadata&exclude=credentials/password/valueResponse
| Error code | Meaning |
|---|---|
1xx |
Information. Stay tuned, operation is in progress. |
2xx |
Success. Operation finished successfully. There are two custom codes:
In this two cases, midPoint returns the OperationResult where there details of executed operations can be found. |
3xx |
Redirection or "in progress". This is returned mostly to indicate two cases:
|
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 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 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).
Access Authorization
The interface authorization needed for executing this type of request. The authorization is needed to access the specific part of the interface. For more information please see this page.
-
http://midpoint.evolveum.com/xml/ns/public/security/authorization-rest-3#searchObjects
Model Authorization
The model authorization for the specific action. This authorization is needed to request/execute the concrete action. The examples are usually quite broad, and the actions can be additionally specified for a more fine-grained authorization. For more information please see this page.
-
http://midpoint.evolveum.com/xml/ns/public/security/authorization-model-3#read
Examples
|
In our examples we are authenticating with the credentials, name "administrator" and password "y0uR_P455woR*d" on a localhost instance running on port 8080. |
For some help regarding the REST examples please see this link:
Search for All Users
curl --user administrator:y0uR_P455woR*d \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X POST http://localhost:8080/midpoint/ws/rest/users/search \
-v \
--data-binary @./samples/rest/query-all.jsonShow data source example for "Search for all" | GitHub
{
"query" : ""
}The response is an HTTP 200 code in case of success with a response body containing the queried items.
Example Output is a list of objects.
{
"@ns" : "http://prism.evolveum.com/xml/ns/public/types-3",
"object" : {
"@type" : "http://midpoint.evolveum.com/xml/ns/public/common/api-types-3#ObjectListType",
"object" : [ {
"@type" : "",
"oid" : "",
"version" : "",
"name" : "",
"metadata" : {},
"operationExecution": {},
"indestructible": ,
"iteration" : ,
"iterationToken" : "",
"archetypeRef": {},
"roleMembershipRef": {},
"activation": {}
}, {
"@type" : "",
"oid" : "",
"version" : "",
"name" : "",
"metadata" : {},
"operationExecution": {},
"indestructible": ,
"iteration" : ,
"iterationToken" : "",
"archetypeRef": {},
"roleMembershipRef": {},
"activation": {}
} ]
}
}Other Example Scenarios
Was this page helpful?
YES
NO
Thanks for your feedback