GET http://localhost:8080/midpoint/ws/rest/self?options=rawREST API
|
REST API feature
This page is an introduction to REST API midPoint feature.
Please see the feature page for more details.
|
Description
The MidPoint REST API is one of the interfaces which gives you the possibility to access and interact with the data present in your midPoint instance.
The REST api gives you a feature rich toolset with which you can operate over different web resources, these are represented as specific endpoints to which you send your operation request.
There are many possibilities which we provide in regard to the endpoints you can access. So many that we have a dedicated page for them.
To display a list of REST endpoints please have a look at:
For a more technical description of our REST api please have a look here:
How To Use
The format of the REST request depends on the type of web resource you try to invoke, the operation which you want to execute and any additional options you wish to specify for the request.
Also, you have to authenticate your self
The most basic form of the url request would be:
Request to read own profile data (raw)
Request to read own profile data (raw) full example using CURL
Content Type
Please have a look at the following example of a search request (we used curl as a REST client):
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.jsonBy changing the content headers in the request you are capable of using different formats in the request body. Please see below for the "request" and "return" content.
For supported media types please refer to the following section of the documentation
Request Content Types
There are multiple possibilities regarding the content type of the request body and also regarding the type of data which will be returned to the client.
The content type can be specified inside the URI of the request. This is done via the addition of a request header.
Content-Type header example, other media types are supported as well
"Content-Type: application/json"The following are examples of the content type:
Content examples
<q:query xmlns:q="http://prism.evolveum.com/xml/ns/public/query-3">
<q:filter>
<q:text>name startsWith "a"</q:text>
</q:filter>
</q:query>{
"query": {
"filter": {
"text": "name startsWith \"a\""
}
}
}query:
filter:
text: "name startsWith \"a\""Reply ("Accept") Content Types
You might need to specify the accepted type of content in case you are interested in a format different from xml (default). This can be done via the "Accept" header
Accept type header example, other media types are supported as well
"Accept: application/json"- TIP
-
Note the "Accept: application/xml" Header usage.
You could have multiple different types of output format:
Reply content type examples
<t:object xmlns:t="http://prism.evolveum.com/xml/ns/public/types-3"
xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
xmlns:apti="http://midpoint.evolveum.com/xml/ns/public/common/api-types-3"
xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
xmlns:icfs="http://midpoint.evolveum.com/xml/ns/public/connector/icf-1/resource-schema-3"
xmlns:org="http://midpoint.evolveum.com/xml/ns/public/common/org-3"
xmlns:q="http://prism.evolveum.com/xml/ns/public/query-3"
xmlns:ri="http://midpoint.evolveum.com/xml/ns/public/resource/instance-3"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="apti:ObjectListType">
<apti:object oid="6506b8f0-9e34-4197-bba1-bd1f75820f12" version="1" xsi:type="c:UserType">
<name>adam</name>
<metadata/>
<operationExecution/>
<iteration>0</iteration>
<iterationToken/>
<activation/>
</apti:object>
<apti:object oid="00000000-0000-0000-0000-000000000002" version="905" xsi:type="c:UserType">
<name>administrator</name>
<description>Description parameter modified via REST</description>
<metadata/>
<operationExecution/>
<indestructible>true</indestructible>
<assignment/>
<iteration>0</iteration>
<iterationToken/>
<archetypeRef oid="00000000-0000-0000-0000-000000000300" relation="org:default" type="c:ArchetypeType"/>
<roleMembershipRef/>
<activation/>
<credentials/>
<behavior/>
<fullName>midPoint Administrator</fullName>
<givenName>midPoint</givenName>
<familyName>Administrator</familyName>
</apti:object>
</t:object>{
"@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" : "c:UserType",
"oid" : "6506b8f0-9e34-4197-bba1-bd1f75820f12",
"version" : "1",
"name" : "adam",
"metadata" : {},
"operationExecution" : {},
"iteration" : 0,
"iterationToken" : "",
"activation" : {}
}, {
"@type" : "c:UserType",
"oid" : "00000000-0000-0000-0000-000000000002",
"version" : "903",
"name" : "administrator",
"description" : "Description parameter modified via REST",
"metadata" : {},
"operationExecution" : [],
"indestructible" : true,
"assignment" : [],
"iteration" : 0,
"iterationToken" : "",
"archetypeRef" : {},
"roleMembershipRef" : [],
"activation" : {},
"credentials" : {},
"behavior" : {},
"fullName" : "midPoint Administrator",
"givenName" : "midPoint",
"familyName" : "Administrator"
} ]
}
}---
'@ns': "http://prism.evolveum.com/xml/ns/public/types-3"
object: !<http://midpoint.evolveum.com/xml/ns/public/common/api-types-3/ObjectListType>
object:
- !<http://midpoint.evolveum.com/xml/ns/public/common/common-3/UserType>
oid: "6506b8f0-9e34-4197-bba1-bd1f75820f12"
version: "1"
name: "adam"
metadata:
operationExecution:
iteration: 0
iterationToken: ""
activation:
- !<http://midpoint.evolveum.com/xml/ns/public/common/common-3/UserType>
oid: "00000000-0000-0000-0000-000000000002"
version: "907"
name: "administrator"
description: "Description parameter modified via REST"
metadata:
operationExecution:
indestructible: true
assignment:
iteration: 0
iterationToken: ""
archetypeRef:
roleMembershipRef:
activation:
credentials:
behavior:
fullName: "midPoint Administrator"
givenName: "midPoint"
familyName: "Administrator"REST Endpoints
Naturally by having a feature rich interface there is no "one size fits them all" way to invoke the operations, so the url will be different in specific use cases. The most common ones you can see at this section of the documentation.
The REST interface provides you with a long list of Endpoints which you can access. The interface also provides you with different kinds of operations, based on the type of object endpoint you choose.
The full collection of Object Endpoints can be found here:
MidPoint Client
To ease up the development of you own implementation of a MidPoint REST client. Please have a look and consider using the midPoint Java Client project:
Common Use Cases
Gotchas
Storing of Authentication Events
By default, midPoint stores the information about authentication events in midPoint focus objects. This behaviour should cause no problem in case of "standard" sign-in behaviour of users. Yet in the case of a service account leveraging the REST api, when large amounts of authentication request might occur, this stored information could build up quite quickly.
Issues which could occur are prolonged response times in case of API calls.
The default behaviour of storing such event after each login can be changed in midPoint configuration. Specifically in changing the "focusBehaviorUpdate" parameter of a "sequence" of your "securityPolicy".
The possible values are:
-
enabled: Behaviour attributes will be updated every login.
-
disabled: Authentication behaviour attributes will not be updated during login.
-
failureOnly: Authentication behaviour attributes will be updated when login failed and when login will be success, but previous login was failed and midPoint need update attributes as is number of login fails and lockout state.
Configuration Example
<securityPolicy>
<!--Other configuration parameters-->
<!-- ... -->
<sequence>
<identifier>rest-default</identifier>
<channel>
<channelId>http://midpoint.evolveum.com/xml/ns/public/common/channels-3#rest</channelId>
<default>true</default>
<urlSuffix>rest-default</urlSuffix>
</channel>
<module>
<identifier>httpBasic</identifier>
<order>1</order>
<necessity>sufficient</necessity>
</module>
<focusBehaviorUpdate>disabled</focusBehaviorUpdate>
<!--Authentication behaviour attributes will not be updated during login.-->
</sequence>
<!-- ... -->
<!--Other configuration parameters-->
</securityPolicy>See Also
-
Evolveum - Team of IAM professionals who developed midPoint
Compliance
This feature is related to the following compliance frameworks:
Was this page helpful?
YES
NO
Thanks for your feedback