Activity - Use HAL links for resource investigations

HAL links

HAL (Hypertext Application Language) is a formatting convention that provides hyperlinks to related resources returned by an API request. For example, a GET /environments/{environmentId}/users/{usersId} request returns data for a specific user resource. Hyperlinks to related resources are represented in a _links object in the JSON response data. Here is a sample that shows the self link for the GET /environments/{environmentId}/users/{usersId} request, which is the URI of the resource itself.

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af"
        },
  }
}

In addition, the response data for the GET /environments/{id}/users/{id} request also shows links to related resources.

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006"
        },
        "population": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/populations/a6c45799-8cec-4f69-8be9-e38c7bbdd7e4"
        },
        "devices": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/devices"
        },
        "roleAssignments": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/roleAssignments"
        },
        "password": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/password"
        },
        "password.reset": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/password"
        },
        "password.set": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/password"
        },
        "password.check": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/password"
        },
        "password.recover": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/password"
        },
        "account.sendVerificationCode": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772"
        }
    },
}

For requests that return a collection of resources, the response data for the GET /environments/{environmentId}/users request also shows links for each returned resource in the _embedded object.

The _embedded links returned by the request can be used as a navigation option to initiate additional API requests to explore related resources. For example, using the _embedded links above, you can initiate a GET /environments/{environmentId}/populations/{populationId} request to return data about the population associated with this user. In addition, you can use the password.set or password.reset links to perform password management actions on this user resource.

HAL link types

There are three common types of HAL links in PingOne API response data:

Relationships

Links that identify a relationship that the current resource has with other resources. For example, every user is associated with a population. The response data describing a user includes a HAL link to the associated population resource.
Navigation

Links that provide paging and navigation controls to access resources returned for large collections. For example, navigation links include self, next, prev, first, and last.
Actions

Links that are used to initiate actions on a particular resource. For example, the response data for a user resource shows several password management actions that, when followed, initiate password operations for that user resource.

Use HAL links to perform an action

This activity returns information about a specified user resources for a specified environment. A relationship _links entity in the response data to the /environments/{environmentId}/users/{usersId}/password endpoint is acted upon to check the password state for the selected user resource.

This scenario illustrates the following operations supported by the PingOne for Customers APIs:

Get information about a specific user within an identified environment.
Verify the password state for the specified user resource.

Workflow order of operations

To use HAL links to check a user resource’s password state, the following tasks must be completed successfully:

Make a GET request to the /environments/{environmentId}/users/{usersId} endpoint to return about the user associated with the specified environment.
Use HAL _links from the response data returned from the /environments/{environmentId}/users/{usersId} request to initiate a GET request to /environments/{environmentId}/users/{usersId}/password to return data about the specified user’s password, including the current status.

Step 1: Get a list of users

You can use GET /environments/{environmentId}/users/{usersId} to return information about the user. If you do not know the environment ID, which is required in the request URL, you can call GET /environments to return a list of environments and their assigned IDs.

The following sample shows the GET /environments/{environmentId}/users/{usersId} operation to return the user data.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/users/{usersId}" \
-H "Authorization: Bearer jwtToken"

The response data returned for this request shows all the property data defined for the specified user. The HAL _links entity for the user resource includes a self link (the URL to this user resource) as well as links to related resources. The data below shows the information:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006"
        },
        "population": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/populations/a6c45799-8cec-4f69-8be9-e38c7bbdd7e4"
        },
        "devices": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/devices"
        },
        "roleAssignments": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/roleAssignments"
        },
        "password": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/password"
        },
        "password.reset": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/password"
        },
        "password.set": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/password"
        },
        "password.check": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/password"
        },
        "password.recover": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/password"
        },
        "account.sendVerificationCode": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772"
        }
    },
    "id": "8ce55f02-2077-4493-9a6d-0385df1f0772",
    "environment": {
        "id": "88c23def-39c9-4646-8d41-aa91a14a1006"
    },
    "population": {
        "id": "a6c45799-8cec-4f69-8be9-e38c7bbdd7e4"
    },
    "createdAt": "2019-03-15T17:49:55.567Z",
    "email": "me@example.com",
    "enabled": true,
    "lifecycle": {
        "status": "ACCOUNT_OK"
    },
    "mfaEnabled": false,
    "name": {
        "given": "Lyman",
        "family": "Stone"
    },
    "updatedAt": "2019-03-15T17:49:55.567Z",
    "username": "jlymanstone"
}

Step 2: Get the password state

The response data from Step 1 includes the URI to the GET /environments/{environmentId}/users/{usersId}/password endpoint, which enables several password actions, including checking the user’s password state. To get the password state for a specific user resource, the password HAL link can be used initiate this action.

The following sample shows the GET /environments/{environmentId}/users/{userId}/password operation to check the user’s password status.

curl -X "GET" ""https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/password" \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/password"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006"
        },
        "user": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772"
        },
        "passwordPolicy": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/passwordPolicies/88c23def-39c9-4646-86d3-01018f6ef0ad"
        },
        "password.check": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/password"
        },
        "password.reset": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/password"
        },
        "password.set": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/password"
        },
        "password.recover": {
            "href": "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/password"
        }
    },
    "environment": {
        "id": "88c23def-39c9-4646-8d41-aa91a14a1006"
    },
    "user": {
        "id": "8ce55f02-2077-4493-9a6d-0385df1f0772"
    },
    "passwordPolicy": {
        "id": "88c23def-39c9-4646-86d3-01018f6ef0ad"
    },
    "status": "MUST_CHANGE_PASSWORD",
    "lastChangedAt": "2019-03-26T18:49:12.572Z",
    "warnings": {
        "failuresRemaining": 4
    }
}

The response data shows the password status property for this resource as MUST_CHANGE_PASSWORD. In this case, the HAL link to the password.reset acton can be used to initiate the operation to reset this user’s password.