Node inventory API v1

Command endpoints

There are two command endpoints of the Node inventory API to create and delete connections in the inventory service database.

POST/command/create-connection

This command endpoint creates a new connection to the inventory service database. All connection database entries contain connection settings used to connect to nodes identified by their certnames. The connection options connect to the certnames provided in the payload via the connection type.

The request body is in the form of a JSON body with the following keys:

• Certnames is an array containing a list of certnames to associate with the given connection details.
   
• The type can be either ssh or winrm. This defines the connection type to be used to access the node when running a task.
   
• Parameters are stored as key/value pairs for the specified transport type.
   
• Sensitive_parameters like usernames and passwords are stored in an encrypted format.
   
• Duplicates value can be either error or replace. This specifies the handling cases when the given certnames conflict with existing certnames stored in the node inventory connections database. 
   

The following table shows the list of parameters for ssh and winrm types.

A successful response for the POST/command/create-connection request is a status code of 201 with a JSON object containing the connection_id for each connection's record. This endpoint also inserts each of the provided certnames into PuppetDB if they are not already present. They can be viewed on the Nodes page.

POST/command/delete-connection

This endpoint removes specified certnames from all associated connection entries in the inventory service database. The request body consists of a JSON object with a certnames key. The key defines a list of certnames to be deleted. If the request of processed successfully, it returns a status code of 204 with an empty body.

Query endpoints

There are two query endpoints of the Node Inventory API to obtain the list of inventory service connections.

GET/query/connections

This endpoint lists all the connection entries in the inventory database. It can also be used to request information about a specific connection. The request uses a GET method with authentication. It can include optional parameters in the URI path - certname, sensitive and extract. 

If the querying is successful, the response is a JSON object containing an items key. This key is an array of objects, each representing a  known connection. All connection objects have the following keys.

• connection_id is the unique identifier for the connections entry.
   
• certnames contains an array of certnames of the matching connection entries.
   
• The type can be ssh or winrm.
   
• parameters describe connection settings.
   
• sensitive_parameters provide permission to access sensitive information.
   

POST/query/connections

This endpoint retrieves the connection details of a set of certnames. The POST request body is a  JSON object. It can be an empty object or with the certname, sensitive and extract parameters. An empty request body returns information on all known connections without sensitive parameters. Connection details for a specific certname can be retrieved by stating it in the certname parameter. The response received for a correct and valid request is the same as the GET/query/connections endpoint.

Node inventory API errors

All error responses of the Node Inventory API as recorded as JSON objects. The error responses have three keys.

• kind defines the kind of error encountered.
• msg defines the error message.
• details is a hash that stores additional information about the error.
   

The common error encountered while using this API are:

• 500: unknown-error
• 406: not-acceptable
• 416: unsupported-type
• 400: json-parse-error
• 400: schema-validation-error
• 403: not-permitted
• 409: duplicate-certnames

Frequently Asked Questions

What is the use of the sensitive and extract parameter in the GET query connection endpoint?

Sensitive stores a boolean value indicating if we want the response to include sensitive connection parameters. The extract parameters contain an array of keys that want the response to include.

What does the error and replace value of the duplicates key do?

Specifying error as the value for duplicates will return a 409 response if there are duplicate certnames. Specifying the replace option overwrites the existing certname with the new connection details if there is a duplicate.

What is the difference between ssh and winrm type connection with respect to their sensitive parameters?

In winRM connection type, the sensitive-parameters object is allowed to contain only the password key. This key specifies the password to authenticate the connection. SSH connection type allows two sensitive parameters - password and sudo-password.

Conclusion

This blog discusses the Node Inventory API v1. It briefly explains the four endpoints and the errors encountered while using the API. Check out our articles on Overview of Puppet Server, Overview of PuppetDB and Configuring PuppetDB. Explore our Library on Coding Ninjas Studio to gain knowledge on Data Structures and Algorithms, Machine Learning, Deep Learning, Cloud Computing and many more! Test your coding skills by solving our test series and participating in the contests hosted on Coding Ninjas Studio! 

Looking for questions from tech giants like Amazon, Microsoft, Uber, etc.? Look at the problems, interview experiences, and interview bundle for placement preparations. Upvote our blogs if you find them insightful and engaging! Happy Coding!