Rules endpoint

Use the rules endpoint to translate a node group rule condition into PuppetDB query syntax.

POST /v1/rules/translate

Translate a node group rule condition into PuppetDB query syntax.

Request format

When Forming node classifier API requests to this endpoint, the body must be a JSON object describing a rule condition. The rule condition must be structured like a rule key for a node group object. To get examples of rule keys, use the GET /v1/groups/<id>/rules endpoint.

You can append the optional format parameter to the end of the URI path to change the response format. The default value is nodes. If you specify format=inventory, the response returns classifier rules in a compatible dot notation format, instead of the PuppetDB AST format.

Response format

If you did not specify the format in your request, or if you specified format=nodes, then the response is a PuppetDB query string. You can use this query string with nodes endpoint in PuppetDB to get a list of nodes matching the rule condition.

Error responses

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

Rules that use structured or trusted facts cannot be converted into PuppetDB queries, because PuppetDB does not yet support structured or trusted facts. If the rule can't be translated into a PuppetDB query, the server returns a 422 Unprocessable Entity untranslatable-rule response with a message describing why the rule can't be translated and a copy of your supplied rule.

If the request doesn't contain a valid rule, the server returns a 400 Bad Request response. There are two common variations of this error:
  • malformed-request: The rule is not valid JSON. The error response body contains a copy of your supplied rule.
  • schema-violation: The rule is valid JSON but the rule grammar is incorrect. Refer to Forming node classifier API requests for information about rule grammar. The details key in the error response body describes the submitted rule object, the schema the object was expected to conform to, and how the submitted object failed to conform to the schema.