Activity - Use HAL links for resource investigations


HAL (Hypertext Application Language) is a formatting convention that provides hyperlinks to related resources returned by an API request. For example, a GET /environments/{id}/users/{id} 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/{id}/users/{id} request, which is the URI of the resource itself.

"_links": {
    "self": {
        "href": "https://api.pingone.com/v1/environments/"
    },

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/02d37832-476a-431b-8a60-d77cecd7005c/users"
        }
    },
    "_embedded": {
        "users": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0"
                    },
                    "password": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/password"
                    },
                    "password.set": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/password"
                    },
                    "password.reset": {
                        "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/password"
                    }

...

For requests that return a collection of resources, the response data for the GET /environments/{id}/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 request to return data about the password state. In addition, you can use the password.set or password.reset links to perform password management operations for this user resource.

Note: For more information about using password.set and password.reset actions, see Working with passwords and password policies.

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 the password.set and password.reset actions that, when followed, perform the password set or reset operations for that user resource.

This activity returns a list of user resources for a specified environment. A relationship _links entity in the response data to the /environments/{id}/users/{id}/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 Platform API services:

  • Get a list of users for an 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:

  1. Make a GET request to the /environments{id}/users service to return a list of user resources associated with the specified environment.

  2. Use HAL _links from the response data returned from the /environments{id}/users request to initiate a GET request to /environments/{id}/users/{id}/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/{Id}/users to return a list of users associated with your environment. 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/{envId}/users operation to return the collection of users resources associated with the specified environment.

curl -X GET "https://api.pingone.com/v1/environments/58f92121-b753-4e7e-8d82-23b5bf80efe5/users" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response data returned for this request shows all users associated with this environment in the HAL _embedded entity. The HAL _links entity for each 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 for one user resource:

"_embedded": {
    "users": [
        {
            "_links": {
                "self": {
                    "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0"
                },
                "password": {
                    "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/password"
                },
                "password.set": {
                    "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/password"
                },
                "password.reset": {
                    "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/password"
                },
            "id": "2c820676-3f02-49fe-b3c6-0fd854e53d4e",
            "environment": {
                "id": "58f92121-b753-4e7e-8d82-23b5bf80efe5"
            },
            "population": {
                "id": "8d01d496-598f-432b-af4d-c77f5908c187"
            },
            "username": "katie.brand",
            "name": {
                "family": "Brand",
                "given": "Katherine"
            },
            "email": "katie.brand@pingdevelopers.com",
            "createdAt": "2017-12-07T15:29:15.284Z",
            "updatedAt": "2017-12-07T15:29:15.284Z"
        },

Step 2: Get the password state

The response data from Step 1 includes the URI to the GET/environments/{id}/users/{id}/password endpoint, which returns information about 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/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/password" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/password"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c"
        },
        "user": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0"
        },
        "passwordPolicy": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/passwordPolicies/02d37832-476a-431b-86d3-01018f6ef0ad"
        },
        "passwordValidation": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/password/validation"
        },
        "password.reset": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/password"
        },
        "password.set": {
            "href": "https://api.pingone.com/v1/environments/02d37832-476a-431b-8a60-d77cecd7005c/users/9a774ad6-b6b6-4179-af87-226cd68955f0/password"
        }
    },
    "environment": {
        "id": "02d37832-476a-431b-8a60-d77cecd7005c"
    },
    "user": {
        "id": "9a774ad6-b6b6-4179-af87-226cd68955f0"
    },
    "passwordPolicy": {
        "id": "02d37832-476a-431b-86d3-01018f6ef0ad"
    },
    "status": "PASSWORD_EXPIRED",
    "lastChanged": "2018-05-15T19:23:25.089Z"
}

The response data shows the password status property for this resource as PASSWORD_EXPIRED.