Making Requests

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.

Supported HTTP Operations

The API supports standard GET,POST,PUT,PATCH,DELETE, & OPTIONS verbs. General usage of these verbs is outlined in the following table.

Verb	Description
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

Forming a Request

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.

REST API Root

https://api.greenstack.cloud/v1

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.

Modifying the Response

The API supports a flexible range of query parameters that allow API responses to be modified, sorted, and filtered as needed.

Sorting Resources

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.

Returning a Subset of Resources

You may return a subset of resources to be returned by specifying a comma-separated list of resource IDs:

https://api.greenstack.cloud/v1/site?id=abcd...,efgh...,ijkl...

Searching for Resources

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:

https://api.greenstack.cloud/v1/site?properties.name=*office*

To return all the sites with a code that starts with SEA:

https://api.greenstack.cloud/v1/site?properties.code=SEA*

Without a wildcard, an exact match is required. For example, to return all BACnet BMS devices:

https://api.greenstack.cloud/v1/bms/device?properties.type=bacnet

The property search fields available will vary by endpoint and each endpoint will define which fields support searches.

Using References

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:

https://api.greenstack.cloud/v1/bms/device?@ref.site:node=abcd...

Bulk and Batch Operations

Some API endpoints support the bulk creation, update, and deletion of resources.

Bulk Resource Creation

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.

[
    {
        "..."
    },
    {
        "..."
    }
]

Bulk Resource Updates

To apply updated properties in bulk, specify a comma-separated list of resource IDs with the update request.