Resource Types (REST)

AM provides the resourcetypes REST endpoint for the following:

Resource types are realm specific; hence the URI for the resource types API can contain a realm component, such as /json{/realm}/resourcetypes. If the realm is not specified in the URI, the top level realm is used.

Resource types are represented in JSON and take the following form. Resource types are built from standard JSON objects and values (strings, numbers, objects, sets, arrays, true, false, and null). Each resource type has a unique, system-generated UUID, which must be used when modifying existing resource types. Renaming a resource type will not affect the UUID.

Explained Example

{
    "uuid": "12345a67-8f0b-123c-45de-6fab78cd01e2",
    "name": "URL",
    "description": "The built-in URL Resource Type available to OpenAM Policies.",
    "patterns": [
        "*://*:*/*?*",
        "*://*:*/*"
    ],
    "actions": {
        "POST": true,
        "PATCH": true,
        "GET": true,
        "DELETE": true,
        "OPTIONS": true,
        "HEAD": true,
        "PUT": true
    },
    "createdBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
    "creationDate": 1422892465848,
    "lastModifiedBy": "id=dsameuser,ou=user,dc=openam,dc=forgerock,dc=org",
    "lastModifiedDate": 1422892465848
}

The values for the fields shown in the description are explained below:

"uuid"

String matching the unique identifier AM generated for the resource type when created.

"name"

The name provided for the resource type.

"description"

An optional text string to help identify the resource type.

"patterns"

An array of resource patterns specifying individual URLs or resource names to protect.

For more information on patterns in resource types and policies, see Specifying Resource Patterns with Wildcards

"actions"

Set of string action names, each set to a boolean indicating whether the action is allowed.

"createdBy"

A string containing the universal identifier DN of the subject that created the resource type.

"creationDate"

An integer containing the creation date and time, in ISO 8601 format.

"lastModifiedBy"

A string containing the universal identifier DN of the subject that most recently updated the resource type.

If the resource type has not been modified since it was created, this will be the same value as createdBy.

"lastModifiedDate"

An string containing the last modified date and time, in ISO 8601 format.

If the resource type has not been modified since it was created, this will be the same value as creationDate.

Before making a REST API call to request manage a policy component, make sure that you have:

Authenticated successfully to AM as a user with sufficient privileges to make the REST API call.
Obtained the session token returned after successful authentication.

When making a REST API call, specify the realm in the path component of the endpoint. You must specify the entire hierarchy of the realm, starting at the Top Level Realm. Prefix each realm in the hierarchy with the realms/ keyword. For example /realms/root/realms/customers/realms/europe.

You must also pass the session token in the HTTP header. For more information about the AM session token and its use in REST API calls, see "Using the Session Token After Authentication".

Querying Resource Types

To list all the resource types in a realm, perform an HTTP GET to the /json{/realm}/resourcetypes endpoint, with a _queryFilter parameter set to true.

Note

If the realm is not specified in the URL, AM returns resource types in the top level realm.

The iPlanetDirectoryPro header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

$ curl \
--header "iPlanetDirectoryPro: AQIC5..." \
--header "Accept-API-Version: resource=1.0" \
https://openam.example.com:8443/openam/json/realms/root/realms/myrealm/resourcetypes?_queryFilter=true
{
    "result":[
        {
            "uuid":"12345a67-8f0b-123c-45de-6fab78cd01e3",
            "name":"LIGHTS",
            "description":"",
            "patterns":[
                "light://*/*"
            ],
            "actions":{
                "switch_off":true,
                "switch_on":true
            },
            "createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
            "creationDate":1431013059131,
            "lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
            "lastModifiedDate":1431013069803
        }
    ],
    "resultCount":1,
    "pagedResultsCookie":null,
    "remainingPagedResults":0
}

Additional query strings can be specified to alter the returned results. For more information, see "Query".

Supported _queryFilter Fields and Operators

Field	Supported Operators
`uuid`	Equals (`eq`), Contains (`co`), Starts with (`sw`)
`name`	Equals (`eq`), Contains (`co`), Starts with (`sw`)
`description`	Equals (`eq`), Contains (`co`), Starts with (`sw`)
`patterns`	Equals (`eq`), Contains (`co`), Starts with (`sw`)
`actions`	Equals (`eq`), Contains (`co`), Starts with (`sw`)

Reading a Specific Resource Type

To read individual resource types in a realm, perform an HTTP GET to the /json{/realm}/resourcetypes endpoint, and specify the UUID in the URL.

Note

If the realm is not specified in the URL, AM uses the top level realm.

The iPlanetDirectoryPro header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

$ curl \
--header "iPlanetDirectoryPro: AQIC5..." \
--header "Accept-API-Version: resource=1.0" \
https://openam.example.com:8443/openam/json/realms/root/realms/myrealm/resourcetypes/12345a67-8f0b-123c-45de-6fab78cd01e3
{
    "uuid":"12345a67-8f0b-123c-45de-6fab78cd01e3",
    "name":"LIGHTS",
    "description":"",
    "patterns":[
        "light://*/*"
    ],
    "actions":{
        "switch_off":true,
        "switch_on":true
    },
    "createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "creationDate":1431013059131,
    "lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "lastModifiedDate":1431013069803
}

Creating a Resource Type

To create a resource type in a realm, perform an HTTP POST to the /json{/realm}/resourcetypes endpoint, with an _action parameter set to create. Include a JSON representation of the resource type in the POST data.

Note

If the realm is not specified in the URL, AM creates the resource type in the top level realm.

The iPlanetDirectoryPro header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

Do not use special characters within resource type, policy, or policy set names (for example, "my+resource+type") when using the AM console or REST endpoints. Using the special characters listed below causes AM to return a 400 Bad Request error. The special characters are: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000).

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: AQIC5..." \
--header "Accept-API-Version: resource=1.0" \
--data '{
    "name":"My Resource Type",
    "actions":{
        "LEFT":true,
        "RIGHT":true,
        "UP":true,
        "DOWN":true
    },
    "patterns":[
        "http://device/location/*"
    ]
}' \
https://openam.example.com:8443/openam/json/realms/root/realms/myrealm/resourcetypes/?_action=create
{
    "uuid":"12345a67-8f0b-123c-45de-6fab78cd01e4",
    "name":"My Resource Type",
    "description":null,
    "patterns":[
        "http://device/location/*"
    ],
    "actions":{
        "RIGHT":true,
        "DOWN":true,
        "UP":true,
        "LEFT":true
    },
    "createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "creationDate":1431099940616,
    "lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "lastModifiedDate":1431099940616
}

Updating a Resource Type

To update an individual resource type in a realm, perform an HTTP PUT to the /json{/realm}/resourcetypes endpoint, and specify the UUID in both the URL and the PUT body. Include a JSON representation of the updated resource type in the PUT data, alongside the UUID.

Note

If the realm is not specified in the URL, AM uses the top level realm.

The iPlanetDirectoryPro header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

Do not use special characters within resource type, policy, or policy set names (for example, "my+resource+type") when using the AM console or REST endpoints. Using the special characters listed below causes AM to return a 400 Bad Request error. The special characters are: double quotes ("), plus sign (+), comma (,), less than (<), equals (=), greater than (>), backslash (\), forward slash (/), semicolon (;), and null (\u0000).

$ curl \
--request PUT \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: AQIC5..." \
--header "Accept-API-Version: resource=1.0" \
--data '{
    "name":"My Resource Type",
    "uuid":"12345a67-8f0b-123c-45de-6fab78cd01e4"
    "actions":{
        "LEFT":true,
        "RIGHT":true,
        "UP":false,
        "DOWN":false
    },
    "patterns":[
        "http://device/location/*"
    ]
}' \
https://openam.example.com:8443/openam/json/realms/root/realms/myrealm/resourcetypes/12345a67-8f0b-123c-45de-6fab78cd01e4
{
    "uuid":"12345a67-8f0b-123c-45de-6fab78cd01e4",
    "name":"My Resource Type",
    "description":null,
    "patterns":[
        "http://device/location/*"
    ],
    "actions":{
        "RIGHT":true,
        "DOWN":true,
        "UP":false,
        "LEFT":false
    },
    "createdBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "creationDate":1431099940616,
    "lastModifiedBy":"id=amadmin,ou=user,dc=openam,dc=forgerock,dc=org",
    "lastModifiedDate":1637667798885
}

Deleting a Specific Resource Type

To delete individual resource types in a realm, perform an HTTP DELETE to the /json{/realm}/resourcetypes endpoint, and specify the UUID in the URL.

Note

If the realm is not specified in the URL, AM uses the top level realm.

The iPlanetDirectoryPro header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

$ curl \
--request DELETE \
--header "iPlanetDirectoryPro: AQIC5..." \
--header "Accept-API-Version: resource=1.0" \
https://openam.example.com:8443/openam/json/realms/root/realms/myrealm/resourcetypes/12345a67-8f0b-123c-45de-6fab78cd01e4
{}

You can only delete resource types that are not being used by a policy set or policy. Trying to delete a resource type that is in use will return an HTTP 409 Conflict status code, with a message such as:

{
    "code": 409,
    "reason": "Conflict",
    "message": "Unable to remove resource type 12345a67-8f0b-123c-45de-6fab78cd01e4 because it is
                referenced in the policy model."
}

Remove the resource type from any associated policy sets or policies to be able to delete it.