api_put() method
Sends a PUT request to the HighBond API.
Caution
HighBond API methods interact with your organization's live Diligent One data. If you have the appropriate permissions, they give you the power to change or delete data that may be important. Carefully consider the consequences of your actions when using the HighBond API.
Note
Some Diligent One resources support PATCH, some support PUT, and some support both request types. For more information, see the HighBond API Reference.
Syntax
hcl.api_put("HighBond API request details", data = request_payload)
Parameters
| Name | Description |
|---|---|
| HighBond API request details |
The request details for the Diligent One resource. hcl.api_put 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 |
| data = request_payload |
The data to send to the Diligent One API server. The payload data must be formatted as JSON. |
Returns
Response object from the HighBond API server.
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")
