Query endpoints

Use the query endpoints to retrieve lists of inventory service connections.

GET /query/connections

List all the connections entries in the inventory database or request information about a specific connection.

Request format

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.
Tip: To return sensitive parameters, the request must include sensitive=true. Otherwise, sensitive parameters are excluded by default.
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"

Response format

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"
    }
  ]
}

POST /query/connections

Retrieve connection details for a set of certnames.

Request format

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.
Tip: To return sensitive parameters, the request must include "sensitive": "true". Otherwise, sensitive parameters are excluded by default.

Here are some examples of JSON bodies for the /query/connections endpoint.

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"]
}

Response format

The successful response is the same as the GET /query/connections endpoint.