Making Requests
Last updated
Last updated
©2019 - 2024 Counterbalance Software LLC
When you make a request to the API, you will specify an HTTP method and a path. Additionally, you might also specify request headers and path, query, or body parameters. The API will return the response status code, response headers, and potentially a response body.
The API reference documentation describes the HTTP method, path, and parameters for every operation. It also displays example requests and responses for each operation.
The API supports standard GET,POST,PUT,PATCH,DELETE, & OPTIONS verbs. General usage of these verbs is outlined in the following table.
| Verb | Description |
|---|---|
The REST API is access via HTTP/S at the root URL below. Refer to Versioning to learn more about how the API version is specified in the URL.
To make a request, first find the HTTP method and the path for the operation that you want to use. The reference documentation will specify which headers, parameters, and request data will be required for each request. You will use this information to build a request to the API.
The API supports a flexible range of query parameters that allow API responses to be modified, sorted, and filtered as needed.
You may specify the sort field and direction used when returning a list of resources. To sort resources, use the following query parameters:
sort.field - specify the property field used for sorting. Each endpoint will specify which properties support sorting.
sort.direction - specify the direction the resources should be sorted. To sort resources in ascending order, set this parameter to asc. To sort resources in descending order, set this parameter to desc.
You may return a subset of resources to be returned by specifying a comma-separated list of resource IDs:
Resource lists may be filtered using a series of property search parameters that return resources based on a set of matching values. You can use a * character to perform wildcard searches.
For example, to return all the sites that contain the word "office" in the name:
To return all the sites with a code that starts with SEA:
Without a wildcard, an exact match is required. For example, to return all BACnet BMS devices:
The property search fields available will vary by endpoint and each endpoint will define which fields support searches.
References allow you to leverage the relationships amongst resources to return related resources using a standard reference syntax. The references available will vary depending on the resource.
Refer to Data Model & Schema documentation to learn more about references and resource relationships.
For example, to return all the BMS devices associated with a specific site:
Some API endpoints support the bulk creation, update, and deletion of resources.
To create resources in bulk, submit the request as an array of objects. Each resource will be evaluated individually, and no resources will be created if an error is generated.
To apply updated properties in bulk, specify a comma-separated list of resource IDs with the update request.
GET
Retrieves existing resources
POST
Creates a new resource and returns it
PUT
Creates a new resource within or attached to an existing resource and returns the new resource
PATCH
Updates an existing resource and returns the updated resource
DELETE
Removes an existing resource and returns nothing
OPTIONS
List available verbs against a resource