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/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca"
},
"population": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/populations/a701eb22-849d-4168-b756-6c20fc087c2f"
},
"password": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
},
"password.reset": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
},
"password.set": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
},
"password.validate": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
},
"password.recover": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
},
"account.sendVerificationCode": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af"
}
},
}
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
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.
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
, andlast
. -
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
andpassword.reset
actions that, when followed, perform the password set or reset 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 aGET
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/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca"
},
"population": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/populations/a701eb22-849d-4168-b756-6c20fc087c2f"
},
"password": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
},
"password.reset": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
},
"password.set": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
},
"password.validate": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
},
"password.recover": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
},
"account.sendVerificationCode": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af"
}
},
"id": "c3042000-188f-4bc7-a269-dee1602cf7af",
"environment": {
"id": "5da98f13-ad62-4234-ba04-2b6e2e85c8ca"
},
"population": {
"id": "a701eb22-849d-4168-b756-6c20fc087c2f"
},
"createdAt": "2019-01-08T20:18:31.264Z",
"email": "lindajones@example.com",
"enabled": true,
"lifecycle": {
"status": "ACCOUNT_OK"
},
"mfaEnabled": false,
"name": {
"given": "Linda",
"family": "Jones"
},
"nickname": "Lindy",
"timezone": "America/New_York",
"title": "Doctor",
"updatedAt": "2019-01-08T20:59:56.871Z",
"username": "lindajones"
}
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/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca"
},
"user": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af"
},
"passwordPolicy": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/passwordPolicies/5da98f13-ad62-4234-86d3-01018f6ef0ad"
},
"password.validate": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
},
"password.reset": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
},
"password.set": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
},
"password.recover": {
"href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/users/c3042000-188f-4bc7-a269-dee1602cf7af/password"
}
},
"environment": {
"id": "5da98f13-ad62-4234-ba04-2b6e2e85c8ca"
},
"user": {
"id": "c3042000-188f-4bc7-a269-dee1602cf7af"
},
"passwordPolicy": {
"id": "5da98f13-ad62-4234-86d3-01018f6ef0ad"
},
"status": "NO_PASSWORD",
"lastChangedAt": "2019-01-08T20:18:31.264Z"
}
The response data shows the password status
property for this resource as NO_PASSWORD
. In this case, the HAL link to the password.set
acton can be used to initiate the operation to set this user’s password.