PuppetDB 1.2 » API » Overview

Since PuppetDB collects lots of data from Puppet, it’s an ideal platform for new tools and applications that use that data. You can use the HTTP API described in these pages to interact with PuppetDB’s data.

Summary

PuppetDB’s API uses a Command/Query Responsibility Separation (CQRS) pattern. This means:

• Data can be queried using a standard REST-style API. Queries are processed immediately.
• When making changes to data (facts, catalogs, etc), you must send an explicit command (as opposed to submitting data without comment and letting the receiver determine intent). Commands are processed asynchronously in FIFO order.

The PuppetDB API consists of the following parts:

• The REST interface for queries
• The HTTP command submission interface
• The wire formats that PuppetDB requires for incoming data

Queries

PuppetDB 1.2 supports versions 1 and 2 of the query API. Version 1 is backwards-compatible with PuppetDB 1.0.x, but version 2 has significant new capabilities, including subqueries.

PuppetDB’s data can be queried with a REST API.

• Specification of the General Query Structure
• Available Operators
• Query Tutorial
• Curl Tips

The available query endpoints are documented in the pages linked below.

Query Endpoints

Version 2

Version 2 of the query API adds new endpoints, and introduces subqueries and regular expression operators for more efficient requests and better insight into your data. The following endpoints will continue to work for the foreseeable future.

• Facts Endpoint
• Resources Endpoint
• Nodes Endpoint
• Fact-Names Endpoint
• Metrics Endpoint

Version 1

Version 1 of the query API works with PuppetDB 1.1 and 1.0. It isn’t deprecated, but we encourage you to use version 2 if you can.

In PuppetDB 1.0, you could access the version 1 endpoints without the /v1/ prefix. This still works but is now deprecated, and we currently plan to remove support in PuppetDB 2.0. Please change your version 1 applications to use the /v1/ prefix.

• Facts Endpoint
• Resources Endpoint
• Nodes Endpoint
• Status Endpoint
• Metrics Endpoint

Experimental

These endpoints are not yet set in stone, and their behavior may change at any time without regard for normal versioning rules. We invite you to play with them, but you should be ready to adjust your application on your next upgrade.

• Report Endpoint
• Event Endpoint

Commands

Commands are sent via HTTP but do not use a REST-style interface.

PuppetDB supports a relatively small number of commands. The command submission interface and the available commands are all described at the commands page:

• Commands (all commands, all API versions)

Unlike the query API, these commands are generally only useful to Puppet itself, and all format conversion and command submission is handled by the PuppetDB terminus plugins on your puppet master.

The “replace” commands all require data in one of the wire formats described below.

Wire Formats

All of PuppetDB’s “replace” commands contain payload data, which must be in one of the following formats. These formats are also linked from the commands that use them.

• Facts wire format
• Catalog wire format
• Report wire format (experimental)

↑ Back to top