Search Operation

Last modified 21 Feb 2024 20:39 +01:00

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
POST http://localhost:8080/midpoint/ws/rest/{endpoint}/search

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

Supported Media Types

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

GetOperationOptionsType

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=resolveNames

Usage 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/value

Response

Error code Meaning

1xx

Information. Stay tuned, operation is in progress.

2xx

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 consistency mechanism.

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:

  • 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 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

  • http://midpoint.evolveum.com/xml/ns/public/security/authorization-rest-3#searchObjects

Examples

Search for all Users
# Authenticating with the credentials "administrator" and password "y0uR_P455woR*d" on a localhost instance running on port 8080
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 --data-binary @pathToMidpointGit\samples\rest\query-all.json -v
Show 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
  1. xrefv:/midpoint/reference/support-4.8/interfaces/rest/operations/examples/search-objects-filter.adoc [Get Users with filter query]

Was this page helpful?
YES NO
Thanks for your feedback