api_get() method
Sends a GET request to the HighBond API.
Syntax
hcl.api_get("HighBond API request details")
Parameters
| Name | Description |
|---|---|
| HighBond API request details |
The request details for the Diligent One resource. hcl.api_get automatically provides the standard portion of the request details in the background. You do not need to explicitly specify these request elements unless you want to override a default value:
For the request syntax for a specific Diligent One resource, see the HighBond API Reference. Note If you explicitly specify host information, you must use the HTTPS protocol to connect with the HighBond API. For example: https://apis-us.highbond.com |
Returns
Response object from the HighBond API server.
Examples
Basic examples
Note
The hcl.api_get() method returns a response object that contains everything returned by the HighBond API server. The response object contains both metadata and data. Typically, you need to apply subsequent processing to the response object to extract data that you can use in a Python/HCL script. For more information, see Advanced examples.
Get a list of all the projects in a Diligent One instance
Returns a list of all the projects in the Diligent One instance in which you are working:
hcl.api_get("projects")
Get a list of all the collections in the Diligent One Results app
Returns a list of all the Results collections in the Diligent One instance in which you are working:
hcl.api_get("collections")
Get a list of all the issues in a project
Returns a list of all the issues in the project with ID 19756:
hcl.api_get("projects/19756/issues")
Get a list of issues and limit the fields in the response
Returns a list of all the issues in the project with ID 19756, and returns only the specified fields for each issue:
hcl.api_get("projects/19756/issues?fields[issues]=title,description,creator_name,created_at,updated_at,owner")
Advanced examples
Access the list of issues in the response object returned by the HighBond API server
Typically you need to manipulate the response object returned by the HighBond API server so that you can work with the data it contains.
Returns a response object that includes a list of all the issues in the project with ID 19756:
response_object = hcl.api_get("projects/19756/issues")
Uses the .json() method from the Python Requests library to extract the JSON-encoded portion of the response object to a Python dictionary. You can now work with the issues data in a Python/HCL script.
import requests hb_issues_dict = response_object.json()
You can also perform both operations above in a single step:
import requests
hb_issues_dict = hcl.api_get("projects/19756/issues").json()
You can print the Python dictionary to screen to see the content. Without any additional formatting, the dictionary is displayed without line breaks, or indentation to set off nested elements:
print(hb_issues_dict)
Uses the .dumps() method from the Python JSON library to apply additional formatting so that the dictionary content is more readable:
import json hb_issues_dict_formatted = json.dumps(hb_issues_dict, indent=4) print(hb_issues_dict_formatted)
Example of formatted output:
{
"data": [
{
"id": "52983",
"type": "issues",
"attributes": {
"title": "Data retention and backup",
"description": null,
"creator_name": null,
"created_at": "2015-05-08T20:59:34Z",
"updated_at": "2016-11-17T18:44:59Z",
"position": 3,
"owner": "Jane Sleaman",
"recommendation": "",
"deficiency_type": "Deficiency",
"severity": "High",
"published": true,
"identified_at": "2015-05-08T20:59:34Z",
"reference": null,
"reference_prefix": "1-A",
"risk": "<p>Data retention and backup policy does not exist</p>\r\n",
"scope": null,
"escalation": null,
"cause": "",
"effect": "",
"cost_impact": 3000.0,
"executive_summary": null,
"executive_owner": null,
"project_owner": null,
"closed": false,
"remediation_status": null,
"remediation_plan": null,
"remediation_date": null,
"actual_remediation_date": null,
"retest_deadline_date": null,
"actual_retest_date": null,
"retesting_results_overview": null,
"custom_attributes": []
},
"relationships": {
"project": {
"data": {
"id": "19756",
"type": "projects"
}
},
"owner_user": {
"data": {
"id": "HWF9X5jpXsS",
"type": "users"
}
},
"executive_owner_user": {
"data": null
},
"project_owner_user": {
"data": null
},
"creator_user": {
"data": null
}
}
}
],
"links": {
"prev": null,
"next": null
}
}
Remarks
Authentication
All HighBond API requests require authentication. You must be a System Admin in at least one Diligent One instance to access the API.
To authenticate, use Launchpad to create a HighBond API token for your account. The token is a string that authenticates you and allows you to securely access the HighBond API. For help creating a token, see Creating and managing HighBond access tokens.
Using a HighBond API token with HighBond API methods
To use a HighBond API token with the HighBond API methods you must assign the token to an HCL variable named v_hb_token. Once the token is assigned, it is automatically used for authentication in the background without any need to explicitly specify it in the Diligent One script. For information about assigning the token to the variable, see Use the Variables window to define an HCL variable.
System user token
Customers that have purchased specific Diligent One toolkits also have the option of authenticating using a generic system user token rather than a token associated with a specific user account.
Specify only the unique portion of the resource URL
When you use a HighBond API method, you need to specify only the unique portion, or endpoint, of the Diligent One resource URL. You do not need to specify the common portion (base URL) or the ID of the Diligent One instance in which you are working. This information is automatically provided in the background.
For example, if you are working in a Diligent One instance with ID 1000236, both of these API requests return an identical response. They both list all the issues in project 19756.
hcl.api_get("projects/19756/issues")hcl.api_get("https://apis.highbond.com/v1/orgs/1000236/projects/19756/issues")
Consult the HighBond API Reference
The request syntax for every Diligent One resource is available in the HighBond API Reference. Here, for example, is the request syntax for getting the list of issues in a project.
If you are using an HCL method to make the request, you can start specifying the syntax at projects/....
If you are making the request from outside Diligent One, you need to specify the entire resource URL, starting with the protocol ( https://... ).
Using a variable in the resource URL
Instead of specifying a literal ID in a resource URL you might have code that requires using a variable in the URL. The resource URL is formatted as a string, so to incorporate a variable in the string you need to use either of the Python techniques shown below.
You can use a Python f-string:
v_project_id = "19756"
hcl.api_get(f"projects/{v_project_id}/issues")
You can use Python string concatenation:
v_project_id = "19756"
hcl.api_get("projects/" + v_project_id + "/issues")
