Import hierarchy endpoint

Use the import hierarchy endpoint to delete all existing node groups from the node classifier service and replace them with the node groups defined in the body of the request.

POST /v1/import-hierarchy

Delete all existing node groups from the node classifier service and replace them with the node groups defined in the body of the submitted request.

Request format

CAUTION: This endpoint deletes all existing node groups, and then creates new node groups based on the content of the request body.

When Forming node classifier API requests to this endpoint, the body must contain an array of node group objects that form a valid and complete node group hierarchy. Valid means that the hierarchy does not contain any cycles (self-referencing inheritance loops). Complete means that every node group in the hierarchy is reachable from the root node group (All Nodes).

Tip: Responses from the GET /v1/groups endpoint are valid input for the /v1/import-hierarchy endpoint.
The request body must be a JSON array containing JSON objects describing the node groups to be created. Use the following keys. You must specify all keys – This endpoint supplies no default values.
Key Definition
name

The name of the node group, as a string.
environment The name of the node group's environment, such as production.
environment_trumps When a node belongs to two or more groups, this Boolean indicates whether this node group's environment overrides environments defined by other node groups.
description A string describing the node group. For no description, supply an empty string.
parent The ID of the node group's parent.
rule

The condition that must be satisfied for a node to be classified into this node group.

For rule formatting assistance, refer to Forming node classifier API requests.
variables An object that defines the names and values of any top-level variables set by the node group. Supply key-value pairs of variable names and corresponding variable values. Variable values can be any type of JSON value. The variables object can be empty if the node group does not define any top-level variables.
classes A object that defines the classes to be used by nodes in the node group. The classes object contains the parameters for each class. Some classes have required parameters. This object contains nested objects – The classes object's keys are class names (as strings), and each key's value is an object that defines class parameter names and their values. Within the nested objects, the keys are the parameter names (as strings), and each value is the parameter's assigned value (which can be any type of JSON value). If no classes are declared, then classes must be supplied as an empty object ({}).
config_data An object that defines the class parameters to be used by nodes in the group. Its structure is the same as the classes object. No configuration data is stored if you supply a config_data object that only contains a class name, such as "config_data": {"qux":{}}.
Note: This key is enabled by the classifier::allow-config-data setting. When set to false, supplying the config_data object triggers a 400 response.

Response format

If the submitted request forms a complete and valid node group hierarchy, and the replacement operation is successful, the endpoint returns a 204 No Content response with an empty body.

Error responses

If there is an error, Node classifier API errors provide error information in the kind key. There are several errors you might encounter with the POST /v1/import-hierarchy endpoint:
Response code Message Description
400 Bad Request schema-violation Keys are missing or the value of any supplied key does not match the required type.
400 Bad Request malformed-request The request's body could not be parsed as JSON.
422 Unprocessable Entity unreachable-groups The node group hierarchy contains node groups that are unreachable from the root node group. The response lists the unreachable node groups.
422 Unprocessable Entity inheritance-cycle The request causes an inheritance cycle. The error response contains a description of the cycle, including a list of the node group names, where each node group is followed by its parent until the first node group is repeated.

You might also encounter some of the errors returned by the POST /v1/groups endpoint.