api_post() method

Sends a POST request to the HighBond API.

Syntax

hcl.api_post("HighBond API request details", data = request_payload)

Parameters

Name	Description
HighBond API request details	The request details for the Diligent One resource. hcl.api_post 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: host information Diligent One region Diligent One instance ID (organization ID) header information 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.

Name

Description

HighBond API request details

The request details for the Diligent One resource.

hcl.api_post 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:

host information
Diligent One region
Diligent One instance ID (organization ID)
header information

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.

Examples

Create an issue in a Diligent One project

You build a request payload that uses JSON formatting and assign the payload to the payload variable. You then use the hcl.api_post method, and reference the payload variable in the method, to create an issue in the project with ID 19756.

Tip

To quickly build payload syntax, copy the appropriate payload syntax block from the HighBond API Reference. After copying the payload block, you can remove key-value pairs that you intend to leave empty.

payload = {"data":
        { 
            "type": "issues",
            "attributes": {
                "description": "Description of issue",
                "owner": "Jane Sleaman",
                "deficiency_type": "Deficiency",
                "title": "Data retention and backup",
                "severity": "High",
                "published": True,
                "identified_at": "2021-11-01T18:15:30Z"
                    }
                }
            }

hcl.api_post("projects/19756/issues", data = payload)

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")