POST /v2/classified/nodes/<name>

Retrieves classification information for the specified node.

Request format

When Forming node classifier API requests to this endpoint, the URI path must contain the name of a specific node, and the body can contain a JSON object using these keys:
Key Definition
fact A JSON object containing regular, non-trusted facts associated with the node. The object contains key/value pairs of fact names and fact values. Fact values can be strings, integers, Booleans, arrays, or objects.
trusted A JSON object containing trusted facts associated with the node. The object contains key/value pairs of fact names and fact values. Fact values can be strings, integers, Booleans, arrays, or objects.
Here is an example of a curl command for the /v2/classified/nodes/<name> endpoint:
type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):4433/classifier-api/v2/classified/nodes/<NAME>"
data='{"fact" : { "<FACT_NAME>" : "<FACT_VALUE>" }}'

curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

Response format

A successful response returns a JSON object using these keys to describe the node's classification:
Key Definition
groups An array of the groups that the node was classified into. Each group is represented by an object containing the group id and the name. Contents of the array are sorted by group name.
environment The name of the environment that the node uses, which is taken from the node groups the node was classified into.
classes An array of strings representing the classes that this node received from the groups it was classified into.
parameters An object containing key/value pairs describing class parameter values for the node's classes if the parameters are different from the default parameters.

Each key/value pair consists of a class name, as a string, and a subsequent object containing the names and values of non-default parameters within the named class.

For example:
{
  "groups": [{"id": "9c0c7d07-a199-48b7-9999-3cdf7654e0bf",
              "name": "a group"},
             {"id": "96d1a058-225d-48e2-a1a8-80819d31751d",
              "name": "b group"}],
  "environment": "staging",
  "classes": ["apache"],
  "parameters": {
    "apache": {
      "keepalive_timeout": 30,
      "log_level": "notice"
    }
  }
}

Error responses

If there is an error, Node classifier API errors provide error information in the kind key.

If the node is classified into multiple node groups that supply conflicting classifications to the node, the server returns a 500 Server error response.

For classification-conflict errors, the msg describes generally why the conflict happened, and the details contains an object that uses the environment, variables, or classes key to indicate the type of conflict (whether it was in setting the environment, setting variables, or setting class parameters). Each key contains value-detail objects describing the specific conflicts:
Value-detail object key Definition
value The specific value having a conflict. For environment and classes, these are strings. For variables, these can be any JSON value type.
from The node group that the node was classified into that caused the conflicting value to be added to the node's classification. Refer to defined_by for further details.
defined_by The node group that actually defined the conflicting value. This is often the from group, but could be an ancestor of that group, due to How node group inheritance works.
The following example demonstrates a conflicting value being inherited from an ancestor group and a conflicting value supplied directly from the assigned node group. The conflicting value Blue Suede Shoes was included in the classification because the node matched the Elvis Presley group (as indicated by from). However, the conflicting value was actually defined by the Carl Perkins group, which is an ancestor of the Elvis Presley group. This caused the child group to inherit the value from the ancestor group. The Since You've Been Gone conflicting value is defined by the same group that the node was assigned to.
{
  "kind": "classification-conflict",
  "msg": "The node was classified into multiple unrelated groups that defined conflicting class parameters or top-level variables. See `details` for a list of the specific conflicts.",
  "details": {
    "classes": {
      "songColors": {
        "blue": [
          {
            "value": "Blue Suede Shoes",
            "from": {
              "name": "Elvis Presley",
              "classes": {},
              "rule": ["=", "nodename", "the-node"],
              ...
            },
            "defined_by": {
              "name": "Carl Perkins",
              "classes": {"songColors": {"blue": "Blue Suede Shoes"}},
              "rule": ["not", ["=", "nodename", "the-node"]],
              ...
            }
          },
          {
            "value": "Since You've Been Gone",
            "from": {
              "name": "Aretha Franklin",
              "classes": {"songColors": {"blue": "Since You've Been Gone"}},
              ...
            },
            "defined_by": {
              "name": "Aretha Franklin",
              "classes": {"songColors": {"blue": "Since You've Been Gone"}},
              ...
            }
          }
        ]
      }
    }
  }
}