curl \ (1)
--user administrator:y0uR_P455woR*d \ (2)
-H "Accept: application/json" \ (3)
-H "Content-Type: application/json" \ (4)
-X POST http://localhost:8080/midpoint/ws/rest/users/search \ (5)
-v \ (6)
--data-binary @./samples/rest/query-all.json (7)How to use the REST API examples
Introduction
The REST API documentation pages contain a large number of examples. If you are trying to use them for the first time, and you are not familiar with the tools, you might face some issues, or maybe have some questions. This page is dedicated to help you with this.
Tools
In the examples used throughout the REST API documentation pages, we use the tool curl as a web client for issuing the REST requests. We use curl because it is a well known, free and open source software. It is well documented, and it is supported on many platforms.
Usually, you will see something similar to the following format of a curl command in our documentation. The example is valid for both Windows shell and UNIX bash usage; in our examples, we use bash as the difference is only in the "new line" escape characters.
curl ^ (1)
--user administrator:y0uR_P455woR*d ^ (2)
-H "Accept: application/json" ^ (3)
-H "Content-Type: application/json" ^ (4)
-X POST http://localhost:8080/midpoint/ws/rest/users/search ^ (5)
-v ^ (6)
--data-binary @./samples/rest/query-all.json (7)| 1 | Invocation of curl. |
| 2 | Authentication with username and password <username:password>. This part of the curl command means that the request is executed by the administrator user with the password "y0uR_P455woR*d". |
| 3 | Reply content type header format. |
| 4 | Response content type header format. |
| 5 | Request with the request method and REST endpoint URI. |
| 6 | Output is more verbose (includes request and response header data and more). |
| 7 | Data to send with the API request. |
Authentication
The midPoint API currently supports only the basic username and password authentication. Refer to REST Authentication for more information.
Payload data
Some operations are also required to contain a data payload. The content differs based on the operation or endpoint of the request.
In our example, we use the --data-binary parameter to mark the beginning of the payload data.
We often reference a file on the file system, path of which needs to be prepended with the @ character.
The ./samples/rest/ directory structure reference is used because we call the sample data from the base directory of the midPoint samples repository.
--data-binary @./samples/rest/query-all.jsonRequest content type
In case you use a REST request which contains additional data in its body, you might want to specify the content type which you use.
This can be done by declaring a specific Content-Type header.
-H "Content-Type: application/json"If no header is declared, application/xml is assumed.
Refer to the list of the supported media types.
Reply content type
The default content reply type is application/xml.
If you want another type returned, you need to use the Accept header:
-H "Accept: application/json"The Accept header supports the same set of media types as the request Content-Type header.
Refer to the list of the supported media types.
Authorizations
There are two types of authorizations which you need to have configured and assigned to the account executing the request.
Firstly, the actual interface access authorizations (e.g., to access the search objects operation).
Secondly, the model authorization. The model authorizations permit or deny specific actions executed in the interface.
Access authorizations
Our examples use the administrator user. The administrator user has the "superuser" authorization role assigned by default. It grants the user a complete access to the interface and model.
On a production environment, the user executing API request should not be an almighty administrator. In such a case, the user has to have the right set of authorizations for the invoked actions.
Each operation documentation article contains a more fine-grained authorizations which you can use.
Model authorizations
As mentioned above, our examples use the administrator user which is granted unlimited powers by default.
In reality, it is a good practice to limit the access of users to only specific parts of the interface and permit only specific actions. Refer to model authorizations for available authorizations. It is best to adhere to the least‑privilege principle.
Troubleshooting
Errors happen; here are some frequent issues and also how to debug them.
Client error
When the client sends a request which cannot be processed, midPoint often responds with a structure called OperationResult. OperationResult contains more information, quite often a large amount of details on the situation.
In the following, example we have an operation result object returned when midPoint was provided a task which should execute some action on a non-existing object.
Example of OperationResult returned in case of client error.
{
"@ns" : "http://prism.evolveum.com/xml/ns/public/types-3",
"object" : {
"@type" : "c:OperationResultType",
"operation" : "addObject",
"status" : "handled_error",
"importance" : "normal",
"start" : "2024-03-08T15:42:05.727+01:00",
"end" : "2024-03-08T15:42:05.762+01:00",
"microseconds" : 35816,
"invocationId" : 5374,
"token" : 1000000000000001288,
"message" : "Reference reportRef refers to a non-existing object dad5370f-6132-496d-8faa-6c1d3daac2b1: Object of type 'ReportType' with OID 'dad5370f-6132-496d-8faa-6c1d3daac2b1' was not found.: Reference reportRef refers to a non-existing object dad5370f-6132-496d-8faa-6c1d3daac2b1: Object of type 'ReportType' with OID 'dad5370f-6132-496d-8faa-6c1d3daac2b1' was not found.",
"partialResults" : [ ]
}
}Missing '@' character in data content file path
A request was issued via curl with the --data-binary property containing a path pointing to a file.
The issue is that the file path was not prepended with the @ character.
When @ is prepended before the string in the --data-binary property value, curl knows that it should look for a file rather than use the string as a payload.
--data-binary @./samples/rest/query-all.jsonTroubleshooting tips
-
An error reply quite often has data in the body.
-
Check the midPoint log for further information.
-
A reply "Unauthorized" points to lacking authorizations of the user invoking the request; these can be either model or access authorizations.
Was this page helpful?
YES
NO
Thanks for your feedback