Query endpoints

When Forming node inventory API requests to this endpoint, the request is a basic GET call with authentication. You can append these optional parameters to the URI path:

• certname: A single certname, as a string. Use this to retrieve an individual node's connection details, rather than details for all nodes.
• sensitive: A Boolean indicating whether you want the response to include sensitive connection parameters. This parameter has a permission gate, and it doesn't work if you don't have the proper permissions.
• extract: Array of keys indicating the information you want the response to include. The connection_id key is always returned, and you can use extract to limit the remaining keys. For example, extract=["type"] limits the response to connection_id and type.

For example:

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/inventory/v1/query/connections?certname='new.node'&sensitive=true"

curl --insecure --header "$type_header" --header "$auth_header" "$uri"

A successful response returns a JSON object containing the items key. The items key is an array of objects, where each object represents a known connection (or a connection for a single node, depending on the request format). The connection objects use these keys:

• connection_id: A string that is the unique identifier for the connections entry.
• certnames: Array of strings that are the certnames of the matching connections entries.
• type: A string describing the connection type, such as ssh or winrm.
• parameters: An object containing arbitrary key/value pairs that describe connection settings.
• sensitive_parameters: If specified in the request, and the requesting user has permission to access this information, this key is an object that contains arbitrary key/value pairs describing the connections sensitive settings.

For example, this response describes four connections. This is the typical format to expect when your request includes no additional parameters:

{
  "items": [
    {
      "connection_id": "3c4df64f-7609-4d31-9c2d-acfa52ed66ec",
      "certnames": ["node.a", "node.b"],
      "type": "ssh",
      "parameters": {
        "tmpdir": "/tmp",
        "port": 1234
      }
    },
    {
      "connection_id": "4932bfe7-69c4-412f-b15c-ac0a7c2883f1",
      "certnames": ["mynode1", "mynode2"],
      "type": "winrm",
      "parameters": {
        "tmpdir": "/tmp",
        "port": 1234
      }
    }
  ]
}

This response describes a connection for a specific certname:

{
  "items": [
    {
      "connection_id": "3c4df64f-7609-4d31-9c2d-acfa52ed66ec",
      "certnames": ["my.node"],
      "type": "ssh",
      "parameters": {
        "tmpdir": "/tmp",
        "port": 1234
      }
    }
  ]
}

This response describes a specific certname and includes the sensitive information:

{
  "items": [
    {
      "connection_id": "3c4df64f-7609-4d31-9c2d-acfa52ed66ec",
      "certnames": ["my.node"],
      "type": "ssh",
      "parameters": {
        "tmpdir": "/tmp",
        "port": 1234
      },
      "sensitive_parameters": {
        "username": "<USERNAME>",
        "password": "<PASSWORD>"
      }
    }
  ]
}

This response describes a specific aspect of a specific connection (because certname and extract were supplied in the request):

{
  "items": [
    {
      "connection_id": "3c4df64f-7609-4d31-9c2d-acfa52ed66ec",
      "certnames": ["my.node"],
      "type": "ssh"
    }
  ]
}

When Forming node inventory API requests to this endpoint, the request body must be a JSON object. At minimum, it must be an empty object ({}), or it can use these keys:

• certnames: An array containing a list of certnames to retrieve from the inventory service database. If omitted, then all connections are returned.
• sensitive: An optional Boolean indicating whether you want the response to include sensitive connection parameters. This parameter has a permission gate, and it doesn't work if you don't have the proper permissions.
• extract: An array of keys indicating the information you want the response to include. The connection_id key is always returned, and you can use extract to limit the remaining keys. For example, ["type"] limits the response to connection_id and type. If omitted, all keys are returned.

An empty request body, which returns information for all known connections but does not include sensitive parameters:

{}

A request for connection details for a specific certname:

{
  "certnames": ["mynode1"]
}

A request for a specific certname, specific keys, and sensitive parameters:

{
  "certnames": ["averygood.device"],
  "sensitive": "true",
  "extract": ["certnames", "sensitive_parameters"]
}