REST API

Last modified 22 Feb 2024 12:02 +01:00

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:

REST Endpoints

For a more technical description of our REST api please have a look here:

Concepts

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

Authentication methods

The most basic form of the url request would be:

Request to read own profile data (raw)
GET http://localhost:8080/midpoint/ws/rest/self?options=raw
Request to read own profile data (raw) full example using CURL

Request to read own profile data

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.

Commonly Used Object Endpoints:
The full collection of Object Endpoints can be found here:

Endpoints

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

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 header example, other media types are supported as well
"Content-Type: application/json"
<q:query xmlns:q="http://prism.evolveum.com/xml/ns/public/query-3">
    <!-- empty query = return all records -->
</q:query>
{
  "query" : ""
}
query: "\n    \n"

Accept ("return") 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:

<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="a9885c61-c442-42d8-af34-8182a8653e3c" version="" xsi:type="c:UserType">
        <name>Jack</name>
        <metadata/>
        <operationExecution/>
        <assignment/>
        <iteration>0</iteration>
        <iterationToken/>
        <roleMembershipRef/>
        <linkRef oid="062ac29f-f296-4824-aeab-9a0feb9e8bd3" relation="org:default" type="c:ShadowType"/>
        <activation/>
        <emailAddress>jacko@evolveum.com</emailAddress>
        <credentials/>
        <givenName>Jack</givenName>
        <familyName>Sparrow</familyName>
    </apti:object>
    <apti:object oid="00000000-0000-0000-0000-000000000002" version="" 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": "a9885c61-c442-42d8-af34-8182a8653e3c",
				"version": "",
				"name": "Jack",
				"metadata": {},
				"operationExecution": [],
				"assignment": [],
				"iteration": 0,
				"iterationToken": "",
				"roleMembershipRef": [],
				"linkRef": {},
				"activation": {},
				"emailAddress": "jacko@evolveum.com",
				"credentials": {},
				"givenName": "Jack",
				"familyName": "Sparrow"
			},
			{
				"@type": "c:UserType",
				"oid": "00000000-0000-0000-0000-000000000002",
				"version": "",
				"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: "a9885c61-c442-42d8-af34-8182a8653e3c"
    version: ""
    name: "Jack"
    metadata:
    operationExecution:
    assignment:
    iteration: 0
    iterationToken: ""
    roleMembershipRef:
    linkRef:
      oid: "062ac29f-f296-4824-aeab-9a0feb9e8bd3"
      relation: "org:default"
      type: "c:ShadowType"
    activation:
    emailAddress: "jacko@evolveum.com"
    credentials:
    givenName: "Jack"
    familyName: "Sparrow"
  - !<http://midpoint.evolveum.com/xml/ns/public/common/common-3/UserType>
    oid: "00000000-0000-0000-0000-000000000002"
    version: ""
    name: "administrator"
    description: "Description parameter modified via REST"
    metadata:
    operationExecution:
    indestructible: true
    assignment:
    iteration: 0
    iterationToken: ""
    archetypeRef:
      oid: "00000000-0000-0000-0000-000000000300"
      relation: "org:default"
      type: "c:ArchetypeType"
    roleMembershipRef:
    activation:
    credentials:
    behavior:
    fullName: "midPoint Administrator"
    givenName: "midPoint"
    familyName: "Administrator"

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

  1. List all users with their profile information.

  2. Get User with the REST API

  3. Create User with the REST API

  4. Assign User Account with the REST API

See Also

Was this page helpful?
YES NO
Thanks for your feedback