---
title: REST API structure
description: The URI scheme for accessing a managed object follows this convention, assuming the IDM web application was deployed at /openidm.
component: pingoneaic
page_id: pingoneaic:idm-rest-api:rest-structure
canonical_url: https://docs.pingidentity.com/pingoneaic/idm-rest-api/rest-structure.html
section_ids:
  rest-uri-scheme: URI scheme
  rest-object-identifier: Object identifiers
  rest-content-negotiation: Content negotiation
  rest-conditional-operations: Conditional operations
---

# REST API structure

## URI scheme

The URI scheme for accessing a managed object follows this convention, assuming the IDM web application was deployed at `/openidm`.

```
/openidm/managed/type/id
```

The URI scheme for accessing a system object follows this convention:

```
/openidm/system/resource-name/type/id
```

An example of a system object in an LDAP directory might be:

```
/openidm/system/ldap/account/07b46858-56eb-457c-b935-cfe6ddf769c7
```

|   |                                                                                                                                                                                                                                                                                                                                                                         |
| - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | For LDAP resources, you should *not* map the LDAP `dn` to the IDM `uidAttribute` (`_id`). The attribute that is used for the `_id` should be immutable. You should therefore map the LDAP `entryUUID` operational attribute to the IDM `_id`, as shown in the following excerpt of the provisioner configuration file:```none
...
"uidAttribute" : "entryUUID",
...
``` |

## Object identifiers

Every managed and system object has an identifier (expressed as id in the URI scheme) used to address the object through the REST API. The REST API allows for client-generated and server-generated identifiers, through PUT and POST methods. The default server-generated identifier type is a UUID. If you create an object using `POST`, a server-assigned ID is generated in the form of a UUID. If you create a managed user object using PUT the client-assigned ID must be in the form of a UUID.

## Content negotiation

The REST API fully supports negotiation of content representation through the `Accept` HTTP header. Currently, the supported content type is JSON. When you send a JSON payload, you must include the following header:

```
Accept: application/json
```

In a REST call (using the `curl` command, for example), you would include the following option to specify the noted header:

```
--header "Content-Type: application/json"
```

You can also specify the default UTF-8 character set as follows:

```
--header "Content-Type: application/json;charset=utf-8"
```

The `application/json` content type is not needed when the REST call does not send a JSON payload.

## Conditional operations

The REST API supports conditional operations through the use of the `ETag`, `If-Match` and `If-None-Match` HTTP headers. The use of HTTP conditional operations is the basis of IDM's optimistic concurrency control system. Clients should make requests conditional in order to prevent inadvertent modification of the wrong version of an object.

**REST API Conditional Operations**

| HTTP Header                                                              | Operation | Description                                                                            |
| ------------------------------------------------------------------------ | --------- | -------------------------------------------------------------------------------------- |
| `If-Match: <rev>`                                                        | PUT       | Update the object if the \<rev> matches the revision level of the object.              |
| `If-Match: *`                                                            | PUT       | Update the object regardless of revision level.                                        |
| `If-None-Match: <rev>`                                                   |           | Bad request.                                                                           |
| `If-None-Match: *`                                                       | PUT       | Create; fails if the object already exists.                                            |
| When the conditional operations `If-Match`, `If-None-Match` are not used | PUT       | Upsert; attempts a create, and then an update; if both attempts fail, return an error. |