Environments endpoints

Use the environments endpoints to retrieve the node classifier's environment data. The responses tell you which environments are available, whether a named environment exists, and which classes exist in a certain environment.

The responses are useful for creating node groups, which must be associated with an environment. You can use the Groups endpoints to create and edit node groups.

The node classifier gets environment information from Puppet. Do not use the environments endpoints to create, update, or delete environments.

GET /v1/environments

Retrieve a list of all environments the node classifier knows about at the time of the request.

Request format

When Forming node classifier API requests to this endpoint, the request is a basic GET call with authentication.

Response format

A successful response is a JSON array of objects. Each object uses these keys to describe an environment:
Key Definition
name The name of the environment, as a string.
sync_succeeded A Boolean indicating whether the environment synced successfully during the last class synchronization.

GET /v1/environments/<name>

Retrieve information about a specific environment. This endpoint is useful for checking whether an environment exists.

Request format

When Forming node classifier API requests to this endpoint, the request is a basic GET call with authentication. The URI path must specify an environment name, such as production. For example:
GET https://localhost:4433/classifier-api/v1/environments/production

Response format

If the environment exists, the endpoint returns a 200 response and a JSON array containing one object. The object uses these keys to describe the specified environment:
Key Definition
name The name of the environment, as a string.
sync_succeeded A Boolean indicating whether the environment synced successfully during the last class synchronization.

Error responses

If there is no environment with the specified name, the endpoint returns a 404 Not Found response with an empty body. Other possible errors follow the usual format for Node classifier API errors.

PUT /v1/environments/<name>

Create a new environment with a specific name.

Request format

When Forming node classifier API requests to this endpoint, the URI path must contain the name you want to assign to the new environment. For example, this request creates an environment called staging:
PUT https://localhost:4433/classifier-api/v1/environments/staging

Response format

If the environment is successfully created, the service returns a 201 Created response and a JSON body describing the environment.

If an environment with the given name already exists, the endpoint might return a 200 OK response.

Error responses

Possible errors follow the usual format for Node classifier API errors.

GET /v1/environments/<environment>/classes

Retrieve a list of all classes (that the node classifier knows about) in a specific environment.

Request format

The /v1/environments/<environment>/classes endpoint returns the node classifier's current class data for the specified environment. The node classifier periodically retrieves class data from the primary server, and you can check the last retrieval time with the GET /v1/last-class-update endpoint. If you want to ensure the response contains the latest data, use the POST /v1/update-classes endpoint to force a retrieval. To get a list of all classes for all environments, use the GET /v1/classes endpoint.

When Forming node classifier API requests to this endpoint, the request is a basic GET call with authentication. The URI path must specify an environment, such as production. For example:
GET https://localhost:4433/classifier-api/v1/environments/production/classes

You can use the GET /v1/environments endpoint to get a list of known environments.

Response format

A successful response is a JSON array of objects. Each object uses these keys to describe a class:
Key Definition
name

The name of the class, as a string.
environment

The name of the environment that this class exists in. Note that the same class can exist in different environments and can have different parameters in each environment.
parameters

An object describing the parameters and default parameter values for the class. The keys of this object are the parameter names (strings). Each value is the default value for the associated parameter as a string, boolean, number, structured value, or null. If the value is null, the parameter is required.
This is an example of one class object:
{
  "name": "apache",
  "environment": "production",
  "parameters": {
    "default_mods": true,
    "default_vhost": true,
    ...
  }
}

For errors, refer to Node classifier API errors.

GET /v1/environments/<environment>/classes/<name>

Retrieve the class with the given name in the given environment.

Request format

The /v1/environments/<environment>/classes/<name> endpoint returns the node classifier's current class data for the specified environment and class. The node classifier periodically retrieves class data from the primary server, and you can check the last retrieval time with the GET /v1/last-class-update endpoint. If you want to ensure the response contains the latest data, use the POST /v1/update-classes endpoint to force a retrieval. To get a list of all classes in an environment, use the GET /v1/environments/<environment>/classes endpoint. To get a list of all classes in all environments, use the GET /v1/classes endpoint.

When Forming node classifier API requests to this endpoint, the request is a basic GET call with authentication. The URI path must specify an environment, such as production, and a class name. For example:
GET https://localhost:4433/classifier-api/v1/environments/production/classes/apache

Response format

A successful response is a JSON array containing one object that uses these keys to describe the class:
Key Definition
name

The name of the class, as a string.
environment

The name of the environment that this class exists in. Note that the same class can exist in different environments and can have different parameters in each environment.
parameters

An object describing the parameters and default parameter values for the class. The keys of this object are the parameter names (strings). Each value is the default value for the associated parameter as a string, boolean, number, structured value, or null. If the value is null, the parameter is required.
For example:
{
  "name": "apache",
  "environment": "production",
  "parameters": {
    "default_mods": true,
    "default_vhost": true,
    ...
  }
}

Error responses

If there is an error, Node classifier API errors provide error information in the kind key.

If the endpoint can't find a class with the specified name, the server returns a 404 Not Found response with an empty body.