GET http://localhost:8080/midpoint/ws/rest/self?options=raw
REST 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.
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.
The most basic form of the url request would be:
Content Type
Please have a look at the following example of a search request (we used curl as a REST client):
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.json
By 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.
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: application/json"
The following are examples of the content type:
<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: application/json"
- TIP
-
Note the "Accept: application/xml" Header usage.
You could have multiple different types of output format:
<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.
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
See Also
-
Evolveum - Team of IAM professionals who developed midPoint