Forming node inventory API requests

Requests to the node inventory service API must be well-formed HTTP(S) requests.

By default, the node inventory service listens on port 8143 and all endpoints are relative to the /inventory/v1 path. For example, the full URL for the /command/create-connection endpoint on localhost is https://localhost:8143/inventory/v1/command/create-connection.

Node inventory API requests must include a URI path following the pattern:

https://<DNS>:8143/inventory/v1/<ENDPOINT>

The variable path components derive from:

  • DNS: Your PE console host's DNS name. You can use localhost, manually enter the DNS name, or use a puppet command (as explained in Using example commands).
  • ENDPOINT: Multiple sections specifying the endpoint, such as command/create-connection or query/connections.

For example, you could use any of these paths to call the GET /query/connections endpoint:

https://$(puppet config print server):8143/inventory/v1/query/connections
https://localhost:8143/inventory/v1/query/connections
https://puppet.example.dns:8143/inventory/v1/query/connections

To form a complete curl command, you need to provide appropriate curl arguments, authentication, and you might need to supply the content type and/or additional parameters specific to the endpoint you are calling.

For general information about forming curl commands, authentication in commands, and Windows modifications, go to Using example commands.

Token authentication

You must authenticate node classifier API requests. You do this by supplying user authentication tokens in an X-Authentication request header.

For instructions on generating, configuring, revoking, and deleting authentication tokens in PE, go to Token-based authentication.

This example uses a token generated with puppet-access login to call the POST /command/create-connection endpoint:

type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/inventory/v1/command/create-connection"
data='{ "certnames": ["new.node"],
        "type": "ssh",
        "parameters": {
            "tmpdir": "/tmp",
            "port": 1234
        },
        "sensitive_parameters": {
            "username": "root",
            "password": "password"
        },
        "duplicates": "replace"
      }'

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

For general information about forming curl commands, authentication in commands, and Windows modifications, go to Using example commands.

This example uses the same token and header pattern to call the POST /query/connections endpoint:

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'"

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

Related information