|
feature
This page describes midPoint feature.
Please see the feature page for more details.
|
Version: 4.4
Status: Public
Stability: STABLE, only backward-compatible changes expected
Platform: RESTful interface
Dependencies: Data Model, Common schema, Query schema
Responsible person: Katarina Bolemant
MidPoint "REST API" is an HTTP-based application programming interface. This interface is a set of web resources that provide access to internal midPoint functionality.
|
Terminology note
We call this interface "REST API" even though it is in fact not entirely RESTful. This API is not hypertext-based. Hypertext is not intended paradigm for this interface. Also, we are not strictly restful in some details. E.g. there are combined web resources that perhaps should be modeled as many smaller web resources if we would follow a strict RESTful approach. However that would be painfully inefficient to use. There are also some parts that are obviously RPC-based. We are doing this to make the API practical as practicality is our highest priority. Yes, we should not call this interface "REST". But almost everyone else does call things like this "REST", and almost everyone expects to see a "REST" interface, so please excuse us. |
MidPoint REST API tries to adhere to the usual HTTP verbs and tries to maintain their original meaning:
| Verb | Meaning and usage |
|---|---|
GET |
Information retrieval. Returns the state of the web resource. Also used to execute searches. |
PUT |
Create 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:
|
PATCH |
Modification 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. |
DELETE |
Delete existing resource. This is used mostly to delete objects. |
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.
However, object retrieval in midPoint can have side effects. Maybe midPoint will find out that an account that HTTP GET is trying to retrieve does not exist. In that case midPoint consistency mechanism may be triggered and it can modify the state of the midPoint objects. Therefore there may be indirect changes in the objects even if GET is used. However, those changes are not direct consequence of the GET operation. Those are consequence of changed environment, and they are only discovered when GET operation is in progress. Those changes would happen anyway, whether GET is used or not. It just may take a bit longer for midPoint to discover that. Therefore we still consider GET to be a safe operation.
MidPoint REST API is not entirely RESTful. There are operations that would be very difficult and very inefficient if modeled as pure RESTful web resource - just because the very nature of those operations is to invoke an operation. Therefore the API web resources are divided into two broad categories:
Create-Read-Update-Delete (CRUD) web resources: Those resources try to adhere to the RESTful approach as close as possible (a.k.a. "almost real REST web resources"). Those resources support the full range of HTTP verbs and they almost behave in a way that can be expected from a RESTful API.
Those resources can be subdivided into two groups:
Individual web resources usually represent a single midPoint object.
They are used to retrieve a specific object, modify it, delete it - and in the very impractical case of PUT also create it.
Typical example is a web resource that represents a single user (e.g. URI …/ws/rest/users/ca8fb11c-72ae-11e7-a09e-9f03da78ca34).
Collection web resources represents collection of objects such as "all users" or "all roles".
Those resources can be used to list and search for objects of a particular type (GET operation).
Collection resources may also be used to create new objects of a particular type (POST operation).
Typical example is a web resource that represents all users (e.g. URI …/ws/rest/users).
Remote Procedure Call (RPC) web resources: Those are simply endpoints for RPC-like operations. They typically support only POST operation. There are also two sub-groups:
Object-related RPC operations: Operations that deal with a specific midPoint object.
They are hierarchically located in the namespace of that object.
Typical examples are operations to suspend and resume tasks (e.g. URI …/ws/rest/tasks/e630b1fe-72af-11e7-8500-771f92d1099a/suspend). Even though they are located in the namespace of (REST-like) object web resource, those are in fact almost pure RPC operations.
Speaking strict REST those operations might in fact be modeled as state changes in the object (web resource) that they "belong" to.
But we have decided to model those operations as RPC-like for several reasons.
Those are non-trivial operations that may have complex consequences, the operations may fail in a non-trivial way, we may need to execute them in an asynchronous mode in the future and so on.
Modeling those as state changes would pollute both the server and the client code with a lot of special-case-handling code and it would make everything more complex and fragile.
Therefore we have decided not to follow strict REST guidelines here and to model those operations as RPC.
Global RPC operations: Operations that do not deal with any specific object, operations that deal with broad selection of objects or simply operations that cannot be classified to any of the above categories. Typical example is an execution of a bulk action.
According to REST architectural style the web resources should be created by PUT operation. However, this assumes that the client knows the URI and therefore it is not very practical. E.g. URI of most midPoint objects contains Object ID, which may or may not be provided by the client. In case that the OID is server-generated the PUT operation is out of question. But even if the OID is client-generated this would expect that the client knows how to construct a URI, which is not very RESTful. Therefore the PUT operation is not very practical.
The usual way how to create a new object in midPoint REST API is to use POST operation to a collection resource.
E.g. new user is created by posting the user object to "users" collection (…/ws/rest/users).
MidPoint will react by creating a new user object and publishing that as a new web resource (with new URI).
MidPoint REST API will respond with and redirection HTTP status (3xx) pointing client to the new URI.
GET operations are supposed to return data. GET invoked on REST-like resources returns what anyone would probably expect: either individual midPoint object or a collection of midPoint objects. All such resources are supposed to behave in the same way, regardless of their type. PUT/POST/PATCH/DELETE for those resources also works in the same way. It returns HTTP status code or indicates an error or asynchronous operation (see below).
However, the situation is very different for the RPC-like resources. The indication of error and asynchronous processing is the same here. But all the rest is different. Those operations usually take data using the body of a POST request. And the data format may be completely different for each operation. The output also differs a lot. Success/failure is always indicated by the HTTP error code. But the data returned on success vary according to the definition of the specific web resource that is used. This is quite expected as those are essentially procedure calls.
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 code | Meaning |
|---|---|
1xx |
Information. Stay tuned, operation is in progress. |
2xx |
Success. Operation finished successfully. There are two custom codes:
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:
|
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 and 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).
Most midPoint operations are currently implemented in a synchronous fashion. When talking about REST API this means that they will not return HTTP response until they are finished. When the operation is finished, midPoint will respond with success (2xx) or error (4xx, 5xx). If new resource is created, redirect status (3xx) is indicated. Retrieving that resource should result in success (2xx).
There are also some operations that are executed asynchronously. In that case midPoint returns HTTP response as soon as the operation is initiated. The status in the response will indicate redirection (3xx). The redirection target is a task that can be used to track operation progress.
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
The following formats and related media types are supported:
| Format | Media type |
|---|---|
XML |
|
JSON |
|
YAML |
|
Some operations return plain text only (text/plain).
Currently supported object types are listed in the following table.
| class | REST type |
|---|---|
ConnectorType |
connectors |
ConnectorHostType |
connectorHosts |
GenericObjectType |
genericObjects |
ResourceType |
resources |
UserType |
users |
ObjectTemplateType |
objectTemplates |
SystemConfigurationType |
systemConfigurations |
TaskType |
tasks |
ShadowType |
shadows |
RoleType |
roles |
ValuePolicyType |
valuePolicies |
NodeType |
nodes |
FormType |
forms |
OrgType |
orgs |
ReportType |
reports |
ReportDataType |
reportData |
SecurityPolicyType |
securityPolicies |
LookupTableType |
lookupTables |
AccessCertificationDefinitionType |
accessCertificationDefinitions |
AccessCertificationCampaignType |
accessCertificationCampaigns |
SequenceType |
sequences |
ServiceType |
services |
CaseType |
cases |
FunctionLibraryType |
functionLibraries |
ObjectCollectionType |
objectCollections |
ArchetypeType |
archetypes |
DashboardType |
dashboards |
Table 1. Supported types.
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 specific 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 specific oid of your object.
Some operations support specifying options influencing the operation execution, e.g. if the execution is made in raw mode, or the shadows are not fetched from the resource, etc. Supported options column shows supported options for different operations. To specify option, use query parameters, e.g. http://localhots:8080/midpoint/api/model/users*?options=raw*
| Operation name | Operation type | Path | Supported options | Data | Response |
|---|---|---|---|---|---|
Create new object |
POST |
/{type} |
Object to create in the XML form |
|
|
Create or update object |
PUT |
/{type}/{oid} |
Object to create in the XML form |
|
|
Get object |
GET |
/{type}/{oid} |
- |
|
|
Modify object |
PATCH, POST |
/{type}/{oid} |
Modifications in XML format |
|
|
Delete object |
DELETE |
/{type}/{oid} |
- |
|
|
Test (configured) Resource |
POST |
/resources/{oid}/test |
No |
- |
|
Import from Resource |
POST |
/resources/{oid}/import/{objectClass} |
No |
- |
|
Find owner of shadow |
GET |
/shadows/{oid}/owner |
No |
- |
|
Import shadow |
POST |
/shadows/{oid}/import |
No |
- |
|
Search |
POST |
/{type}/search |
Query in XML format |
|
|
Suspend tasks |
POST |
/tasks/{oid}/suspend |
No |
- |
|
Resume tasks |
POST |
/tasks/{oid}/resume |
No |
- |
|
Schedule task now |
POST |
/tasks/{oid}/run |
No |
- |
|
Notify change |
POST |
/notifyChange |
No |
Resource object shadow change description |
|
Generate value for concrete object |
POST |
/{type}/{oid}/generate |
No |
Policy for items describing how to generate the value (PolicyItemsDefinitionType) |
|
Generate value |
POST |
/rpc/generate |
No |
PolicyItemsDefinitionType |
|
Validate value for concrete object |
POST |
/{type}/{oid}/validate |
No |
PolicyItemsDefinitionType |
|
Validate value |
POST |
/rpc/validate |
No |
PolicyItemsDefinitionType |
|
Get user’s value policy |
GET |
/users/{oid}/policy |
No |
|
|
Get 'self' |
GET |
/self |
No |
|
|
Search objects by type |
GET |
/{type} |
|
||
Reset credentials |
POST |
/users/{oid}/credential |
No |
ExecuteCredentialResetRequestType - specify reset method and new password |
|
Execute script |
POST |
/rpc/executeScript |
No |
ExecuteScriptType |
|
|
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. Sometimes the newlines are not correctly handled during the transfer.
(See MID-5229.) If that occurs, please use |
The source files used here for the samples can be found at our git repository.
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 -vcurl --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 -vcurl --user administrator:5ecr3t -X GET http://localhost:8080/midpoint/ws/rest/resources/ef2bc95b-76e0-48e2-86d6-3d4f02d3e1a2curl --user administrator:5ecr3t -H "Accept: application/json" -X GET https://demo.evolveum.com:443/midpoint/ws/rest/resources/ef2bc95b-76e0-48e2-86d6-3d4f02d3e1a2curl --user administrator:5ecr3t -X POST http://localhost:8080/midpoint/ws/rest/resources/ef2bc95b-76e0-48e2-86d6-3d4f02d3e1a2/testcurl --user administrator:5ecr3t -H "Content-Type: application/xml" -X POST http://localhost:8080/midpoint/ws/rest/resources/ef2bc95b-76e0-48e2-86d6-3d4f02d3e1a2/import/AccountObjectClasscurl --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.)
Modifies the user "administrator":
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.xmlSearch all accounts:
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.xmlSearch all users:
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.xmlcurl --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| Version | Date | Description | Change Author |
|---|---|---|---|
3.3 |
December 2015 |
Declared as stable version |
Radovan Semancik |
2013-2015 |
untracked improvements |
Katarina Valalikova |
|
April 2013 |
Initial version |
Katarina Valalikova |
Evolveum - Team of IAM professionals who developed midPoint