Using the Razor API

The Razor API is REST-based.

By default, API calls are sent over HTTPS with TLS/SSL. The default URL for the API entrypoint is https://localhost:8151/api. This URL varies if you're running the Razor client on a different machine than the server, or if you changed the default port due to a port conflict.

The API uses JSON exclusively, and all requests must set the HTTP Content-Type header to application/json and must Acceptapplication/json in the response.

The Razor API is stable, and clients can expect operations that work against this version of the API to work against future versions of the API. However, we might add information or functionality to the API, so clients must ignore anything in responses they receive from the server that they don't understand.

Structure and keys

Everything underneath /api is part of the public API and is stable.

Note: The /svc namespace is an internal namespace used for communication with the iPXE client, the microkernel, and other internal components of Razor. This namespace is not enumerated under /api and has no stability guarantee. We recommend making /svc URLs available only to that part of the network that contains nodes that need to be provisioned.

The top-level /api entrypoint serves as the start for navigating through the Razor command and query facilities. For example, given the default API URL, call GET https://razor:8151/api to view the API.

The response is a JSON object with the following keys:

  • commands — The commands available on this server.
  • collections — Read-only queries available on this server.
  • version — The version of Razor that is running on the server. The version should be used only for diagnostic purposes and for bug reporting, and never to decide whether the server supports a certain operation or not.

Each of those keys contains a JSON array, with a sequence of JSON objects that have the following keys:

  • name — A human-readable label for an object, usually unique only among objects of the same type on the same server.
  • id — The URL of an entity. A GET request against a URL with an id attribute produces a representation of the object.
  • rel — A "spec URL" that indicates the type of data contained. Use this key to discover the endpoint that you want to follow, rather than using the name.

For example, {"name":"add-policy-tag", "rel":"https://api.puppetlabs.com/razor/v1/commands/add-policy-tag", "id":"https://localhost:8151/api/commands/add-policy-tag"}.

Commands

The list of commands that the Razor server supports is returned as part of a request to GET /api in the commands array. Clients can identify commands using the rel attribute of each entry in the array, and make their POST requests to the URL given in the id attribute.

The id URL for each command supports the following HTTP methods:

  • GET — Retrieve information about the command, such as a help text and machine-readable information about the parameters this command takes.

  • POST — Execute the command. Command parameters are supplied in a JSON document in the body of the POST request.

Commands are generally asynchronous and return a status code of 202 Accepted on success. The response from a command generally has this form:

   {
     "result":"Policy win2012r2 disabled",
     "command":"http://razor:8088/api/collections/commands/74"
   }

Here, result is a human-readable explanation of what the command did, and command points into the collection of all the commands that were ever run against this server. Performing a GET against the command URL provides additional information about the execution of this command, such as the status of the command, the parameters sent to the server, and details about errors.

Tip: Most client commands allow positional arguments, which can save keystrokes.

Collections

In addition to the supported commands above, a GET /api request returns a list of supported collections in the collections array.

Each entry contains at minimum the following keys:

  • name — A human-readable name for the collection.
  • id — The endpoint through which the collection can be retrieved (via GET).
  • rel — The type of the collection.

A GET request to the id of a collection returns a JSON object The spec property of that object indicates the type of collection. The total indicates how many items there are in the collection in total (not just how many were returned by the query). The items value is the actual list of items in the collection, a JSON array of objects. Each object has these properties:

  • id — A URL that uniquely identifies the object. A GET request to this URL provides further detail about the object.
  • spec — A URL that identifies the type of the object.
  • name — A human-readable name for the object.

Object details

Performing a GET request against the id of an item in a collection returns further detail about that object. Different types of objects provide different properties.

For example, here is a sample tag listing:

{
  "spec": "http://api.puppetlabs.com/razor/v1/collections/tags/member",
  "id": "https://razor:8151/api/collections/tags/anything",
  "name": "anything",
  "rule": [ "=", 1, 1],
  "nodes": {
    "id": "http://razor:8151/api/collections/tags/anything/nodes",
    "count": 2,
    "name": "nodes"
   },
  "policies": {
    "id": "http://razor:8151/api/collections/tags/anything/policies",
    "count": 0,
    "name": "policies"
   }
}

References to other resources are represented as a single JSON object (in the case of a one-to-one relationship) or an array of JSON objects (for a one-to-many or many-to-many relationship). Each JSON object contains these fields:

  • id — A URL that uniquely identifies the associated object or collection of objects.
  • spec — The type of the associated object.
  • name — A human-readable name for the object.
  • count — The number of objects in the associated collection.

Querying the node collection

You can query nodes based on hostname or fields stored in hw_info.

  • hostname — A regular expression to match against hostnames. The results include partial matches, so hostname=example returns all nodes whose hostnames include example.
  • fields stored in hw_info — mac, serial, asset, and uuid.

For example, the following queries the UUID to return the associated node:

/api/collections/nodes?uuid=9ad1e079-b9e3-347c-8b13-9b42cbf53a14'

{
  "items": [
   {
      "id": "https://razor.example.com:8151/api/collections/nodes/node14",
      "name": "node14",
      "spec": "http://api.puppetlabs.com/razor/v1/collections/nodes/member"
    }],
  "spec": "http://api.puppetlabs.com/razor/v1/collections/nodes"
}

Paging collections

The nodes and events collections are paginated.

GET requests for them can include the following parameters to limit the number of items returned:

  • limit — Return this many items.
  • start — Return items starting at start.