http://localhost:8080/midpoint/ws/rest/{endpoint}/{oid}?options=raw
Get Operation
Description
Request for data related to a specific object. The information contains the properties and relations of this object as well as metadata and other technical information.
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.
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.
If you want to make sure no consistency related change might occur, use the raw option set to true in your get queries. As in this example:
Request
Use the HTTP GET method with your request.
GET http://localhost:8080/midpoint/ws/rest/{endpoint}/{oid}
GET http://localhost:8080/midpoint/ws/rest/self
Additionally, you have to supply header information, and optionally you can also specify query options as a parameter of your request.
For more information please have a look at the following sections.
Headers
Regarding authorization type, the "Basic" Authorization header should be used.
Authorization: Basic {Base64EncodedCredentials}
To specify the provided content type, please use the "Content-Type" header payload in the body:
"Content-Type: application/json"
You might need to specify the accepted type of content in case you are interested in a format different from xml (default):
"Accept: application/json"
Body
The get operation does not need to contain any specific payload data in the body of the request.
Options and Functions
Example of usage of options:
The "get" operations support specifying options influencing the operation execution. You can find the supported options in these references:
Usage of Operation Options
To use a boolean based operation option with your request, append a question mark "?" to the original request URI, then type in the "option=" string after which you append the name of the option to be used.
Options can be chained with the "&" character if you want to use multiple options in your request.
Example:
?options=raw&options=resolveNames
Usage of Exclude
To exclude an attribute in the output of your request, you can specify the "exclude" parameter in your query request. The attribute which is mentioned after the equals sign will be excluded. In case of excluding multiple attributes, specify each exclude with an "&" character after each other.
Example:
?exclude=metadata&exclude=credentials/password/value
Response
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).
The response is a set of identity data describing the fetched object. This example had some technical information and metadata related to the environment removed before publishing.
Show Response Example
{
"user" : {
"oid" : "00000000-0000-0000-0000-000000000002",
"name" : "administrator",
"indestructible" : true,
"assignment" : [ {
"@id" : 1,
"identifier" : "superuserRole",
"targetRef" : {
"oid" : "00000000-0000-0000-0000-000000000004",
"relation" : "org:default",
"type" : "c:RoleType"
},
"activation" : {
"effectiveStatus" : "enabled"
}
}, {
"@id" : 2,
"identifier" : "archetype",
"targetRef" : {
"oid" : "00000000-0000-0000-0000-000000000300",
"relation" : "org:default",
"type" : "c:ArchetypeType"
},
"activation" : {
"effectiveStatus" : "enabled"
}
} ],
"iteration" : 0,
"iterationToken" : "",
"archetypeRef" : {
"oid" : "00000000-0000-0000-0000-000000000300",
"relation" : "org:default",
"type" : "c:ArchetypeType"
},
"roleMembershipRef" : [ {
"oid" : "00000000-0000-0000-0000-000000000300",
"relation" : "org:default",
"type" : "c:ArchetypeType"
}, {
"oid" : "00000000-0000-0000-0000-000000000004",
"relation" : "org:default",
"type" : "c:RoleType"
} ],
"credentials" : {
"password" : {
"value" : {
"clearValue" : "5ecr3t"
}
},
"fullName" : "midPoint Administrator",
"givenName" : "midPoint",
"familyName" : "Administrator"
}
}
}
Access Authorization
The interface authorization needed for executing this type of request. The authorization is needed to access the specific part of the interface. For more information please see this page.
-
http://midpoint.evolveum.com/xml/ns/public/security/authorization-rest-3#getObject
-
http://midpoint.evolveum.com/xml/ns/public/security/authorization-rest-3#getSelf
Model Authorization
The model authorization for the specific action. This authorization is needed to request/execute the concrete action. The examples are usually quite broad, and the actions can be additionally specified for a more fine-grained authorization. For more information please see this page.
-
http://midpoint.evolveum.com/xml/ns/public/security/authorization-model-3#get
Examples
In our examples we are authenticating with the credentials, name "administrator" and password "y0uR_P455woR*d" on a localhost instance running on port 8080. |
For some help regarding the REST examples please see this link:
curl --user administrator:y0uR_P455woR*d \
-H "Accept: application/json" \
-X GET http://localhost:8080/midpoint/ws/rest/users/00000000-0000-0000-0000-000000000002?options=raw \
-v
Show JSON Example
The example is simplified, some properties were removed to keep the example output "short". This example does not contain all possible properties of this object type.
{
"user" : {
"oid" : "00000000-0000-0000-0000-000000000002",
"name" : "administrator",
"indestructible" : true,
"assignment" : [ {
"@id" : 1,
"identifier" : "superuserRole",
"targetRef" : {
"oid" : "00000000-0000-0000-0000-000000000004",
"relation" : "org:default",
"type" : "c:RoleType"
},
"activation" : {
"effectiveStatus" : "enabled"
}
}, {
"@id" : 2,
"identifier" : "archetype",
"targetRef" : {
"oid" : "00000000-0000-0000-0000-000000000300",
"relation" : "org:default",
"type" : "c:ArchetypeType"
},
"activation" : {
"effectiveStatus" : "enabled"
}
} ],
"iteration" : 0,
"iterationToken" : "",
"archetypeRef" : {
"oid" : "00000000-0000-0000-0000-000000000300",
"relation" : "org:default",
"type" : "c:ArchetypeType"
},
"roleMembershipRef" : [ {
"oid" : "00000000-0000-0000-0000-000000000300",
"relation" : "org:default",
"type" : "c:ArchetypeType"
}, {
"oid" : "00000000-0000-0000-0000-000000000004",
"relation" : "org:default",
"type" : "c:RoleType"
} ],
"credentials" : {
"password" : {
"value" : {
"clearValue" : "5ecr3t"
}
},
"fullName" : "midPoint Administrator",
"givenName" : "midPoint",
"familyName" : "Administrator"
}
}
}