Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

MidPoint REST API tries to adhere to the usual HTTP verbs and tries to maintain their original meaning:

VerbMeaning and usage
GETInformation retrieval. Returns the state of the web resource. Also used to execute searches.
PUTCreate new web resource. This usually means creation of a new object. However, the client has to provide a complete object, including the identifier (URI). Which is not entirely practical, as this means that the client needs to know how to properly construct the URI. Therefore this operation is seldom used.
POST

POST is used for several purposes:

  • Create new web resources without the need to know the URI. POST to a collection web resource will result that a new sub-resource is created.
  • As an equivalent for PATCH operation (see below). Some HTTP clients have problems when using non-standard verbs. Therefore we provide POST as an alternative way to modify objects.
  • To pass data to an RPC-like operation.
PATCHModification of existing web resource. Usually modification of existing midPoint object. This is non-standard HTTP verb. The usage of PATCH is preferred because its meaning is much more clear than the desperately overloaded meaning of POST. However, POST is provided as an equivalent to PATCH for HTTP clients that have problems with non-standard verbs.
DELETEDelete existing resource. This is used mostly to delete objects.

Safe GET

HTTP GET  is a safe operation. The use of GET does not change the state of a web resource. GET will never cause a (direct) modification. This is given by the REST architectural style. We consider this to be a very good idea and this approach is adopted by midPoint REST API.

...

Operation success and errors are always indicated by the HTTP error code. MidPoint REST API maintains the original HTTP meaning of the error code classes:

Error codeMeaning
1xxInformation. 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 an 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).

...

Use basic authentication. Username and password should correspond to the username and password of appropriately privileged midPoint user. For example, the default ones are:

Username: administrator

Password: 5ecr3t

Supported media types

XML (The following formats and related media types are supported:

FormatMedia type
​XML

application/xml

...

, application/*+xml, text/xml​

JSONapplication/json

...

YAML

...

application/yaml, application/yml, application/*+yaml, application/*+yml
text/yaml, text/yml, text/*+yaml, text/*+yml

Note: There is no official registered media type.

Some operations return plain text only (text/plain).

Supported object types

Currently supported object types are listed in the following table.

classREST type
ConnectorTypeconnectors
ConnectorHostTypeconnectorHosts
GenericObjectTypegenericObjects
ResourceTyperesources
UserTypeusers
ObjectTemplateTypeobjectTemplates
SystemConfigurationTypesystemConfigurations
TaskTypetasks
ShadowTypeshadows
RoleTyperoles
ValuePolicyTypevaluePolicies
NodeTypenodes
FormTypeforms
OrgTypeorgs
ReportTypereports
ReportOutputTypereportOutputs
SecurityPolicyTypesecurityPolicies
AccessCertificationDefinitionTypeaccessCertificationDefinitions
AccessCertificationCampaignTypeaccessCertificationCampaigns
ServiceTypeservices
FunctionLibraryTypefunctionLibraries
ObjectCollectionTypeobjectCollections
ArchetypeTypearchetypes
DashboardTypedashboards

Table 1. Supported types.

Supported operations

The base URL of REST API is http://localhost:8080/midpoint/ws/rest  (alternatively to /ws/rest paths /api/model and /rest/model are also supported).

  • Use the base URL + path from the table below to request concrete operation. 
  • Supply the {type} with the concrete type of object you want to add (or modify, delete, search, etc). Supported types are listed in Table 1 above.
  • Supply the {oid} with the concrete oid of your object.
Operation nameOperation typePathDataResponse
Create new objectPOST

/{type} 

Object to create in the XML form

201 Created, Location set to point to the newly created object

240 Handled error, OperationResult is returned in the body

250 Partial error, OperationResult is returned in the body

Create or update objectPUT

/{type}/{oid}

Object to create in the XML form

201 Created, Location set to point to the newly created object

240 Handled error, OperationResult is returned in the body

250 Partial error, OperationResult is returned in the body

Get objectGET/{type}/{oid}-

200 OK, current object in the response body

Modify object  PATCH, POST/{type}/{oid}Modifications in XML format

204 No Content

240 Handled error, OperationResult is returned in the body

250 Partial error, OperationResult is returned in the body

Delete objectDELETE/{type}/{oid}-

204 No Content

240 Handled error, OperationResult is returned in the body

250 Partial error, OperationResult is returned in the body

Test (configured) Resource

POST/resources/{oid}/test-200 OK, result of the test operation in the body

Import from Resource

POST

/resources/{oid}/import/{objectClass}

-

303 See Other, Location set to point to the concrete "import" task

Find owner of shadow

GET

/shadows/{oid}/owner

-

200 OK, owner of the shadow returned in the response body

Import shadow

POST

/shadows/{oid}/import

-

200 OK, result of the import operation in the body

SearchPOST

/{type}/search

Query in XML format200 OK, list of found objects in the body
Suspend tasksPOST/tasks/{oid}/suspend-204 No Content
Resume tasksPOST/tasks/{oid}/resume-202 Accepted
Schedule task nowPOST/tasks/{oid}/run-202 Accepted
Notify changePOST/notifyChangeResource object shadow change description200 OK
Generate value for concrete objectPOST/{type}/{oid}/generatePolicy for items describing how to generate the value (PolicyItemsDefinitionType)

200 OK

240 Handled error, OperationResult is returned in the body

250 Partial error, OperationResult is returned in the body

Generate valuePOST/rpc/generatePolicyItemsDefinitionType

200 OK

240 Handled error, OperationResult is returned in the body

250 Partial error, OperationResult is returned in the body

Validate value for concrete objectPOST/{type}/{oid}/validatePolicyItemsDefinitionType

200 OK

240 Handled error, OperationResult is returned in the body

250 Partial error, OperationResult is returned in the body

Validate valuePOST/rpc/validatePolicyItemsDefinitionType

200 OK

240 Handled error, OperationResult is returned in the body

250 Partial error, OperationResult is returned in the body

Get 'self'GET/self
200 OK, current object in the response body
Get objects by typeGET/{type}
200 OK, list of object of specified type in the response body
Reset credentialsPOST/users/{oid}/credentialExecuteCredentialResetRequestType - specify reset method and new password 200 OK, ExecuteCredentialResetResponseType returned in the body. 

...

Usage samples

Info

If you are using file as a source for the data in the REST call with curl, please, don't forget to use '@' before the path to your file.

Info

Sometimes the newlines are not correctly handled during the transfer. (See

Jira
serverEvolveum Jira
serverId701b45f2-090c-3276-8ac9-f45eedf731bc
keyMID-5229
.) If that occurs, please use --data-binary  instead of -d.

The source files used here for the samples can be found at our git repository.

Create new Resource (OpenDJ)

Code Block
languagebash
curl --user administrator:5ecr3t -H "Content-Type: application/xml" -X POST http://localhost:8080/midpoint/ws/rest/resources -d @pathToMidpointGit\samples\rest\opendj-resource-sync.xml -v

Create or Update object

Code Block
languagebash
curl --user administrator:5ecr3t -H "Content-Type: application/xml" -X PUT http://localhost:8080/midpoint/ws/rest/resources/ef2bc95b-76e0-48e2-86d6-3d4f02d3e1a2 -d @pathToMidpointGit\samples\rest\opendj-resource-sync.xml -v

Get object

Code Block
languagebash
curl --user administrator:5ecr3t -X GET http://localhost:8080/midpoint/ws/rest/resources/ef2bc95b-76e0-48e2-86d6-3d4f02d3e1a2

...

Code Block
languagebash
titleGet Object in JSON format
curl --user administrator:5ecr3t -H "Accept: application/json"  -X GET https://demo.evolveum.com:443/midpoint/ws/rest/resources/ef2bc95b-76e0-48e2-86d6-3d4f02d3e1a2

Test Resource (OpenDJ)

Code Block
languagebash
curl --user administrator:5ecr3t -X POST http://localhost:8080/midpoint/ws/rest/resources/ef2bc95b-76e0-48e2-86d6-3d4f02d3e1a2/test

Import accounts from resource (Account object class from OpenDJ)

Code Block
languagebash
curl --user administrator:5ecr3t -H "Content-Type: application/xml" -X POST http://localhost:8080/midpoint/ws/rest/resources/ef2bc95b-76e0-48e2-86d6-3d4f02d3e1a2/import/AccountObjectClass

Find owner of shadow

Code Block
languagebash
curl --user administrator:5ecr3t -X GET http://localhost:8080/midpoint/ws/rest/shadows/d0133de0-0d7b-4a36-9d9d-98640216804a/owner

(Note: d0133de0-0d7b-4a36-9d9d-98640216804a is expected to be the OID of a shadow. If you would like to really execute this command, replace it by a concrete OID from your repository.)

Modify object (assign account)

...

Modifies the user "administrator":

Code Block
languagebash
curl --user administrator:5ecr3t -H "Content-Type: application/xml" -X PATCH http://localhost:8080/midpoint/ws/rest/users/00000000-0000-0000-0000-000000000002 -d @pathToMidpointGit\samples\rest\modification-assign-account.xml

Searching

Search

...

all accounts

...

:

Code Block
languagebash
curl--user administrator:5ecr3t -H "Content-Type: application/xml" -X POST http://localhost:8080/midpoint/ws/rest/shadows/search -d @pathToMidpointGit\samples\rest\query-all-accounts.xml

Search

...

all users

...

:

Code Block
languagebash
curl --user administrator:5ecr3t -H "Content-Type: application/xml" -X POST http://localhost:8080/midpoint/ws/rest/users/search -d @pathToMidpointGit\samples\rest\query-all-users.xml

Notify change

Code Block
languagebash
curl --user administrator:5ecr3t -H "Content-Type: application/xml" -X POST http://localhost:8080/midpoint/ws/rest/notifyChange -d @pathToMidpointGit\samples\rest\notify-change-modify-password.xml -v

History

Version

Date

Description

Change Author

3.3December 2015Declared as stable versionRadovan Semancik

2013-2015untracked improvements

Katarina Valalikova


April 2013

Initial version

Katarina Valalikova

Artifacts

None. Swagger definition is planned in the future.

...