Environment modules

The environment modules API will return information about what modules are installed for the requested environment.

GET /puppet/v3/environment_modules

Supported HTTP Methods

GET

Supported Formats

JSON

Responses

GET request with results

GET /puppet/v3/environment_modules

HTTP/1.1 200 OK
Content-Type: application/json

[{
    "modules": [
        {
            "name": "puppetlabs/ntp",
            "version": "6.0.0"
        },
        {
            "name": "puppetlabs/stdlib",
            "version": "4.14.0"
        }
    ],
    "name": "env"
},
{
    "modules": [
        {
            "name": "puppetlabs/stdlib",
            "version": "4.14.0"
        },
        {
            "name": "puppetlabs/azure",
            "version": "1.1.0"
        }
    ],
    "name": "production"
}]

GET /puppet/v3/environment_modules?environment=:environment

Supported HTTP Methods

GET

Supported Formats

JSON

Query Parameters

Provide one parameter to the GET request:

  • environment: Request information about modules pertaining to the specified environment only.

Responses

GET request with results

GET /puppet/v3/environment_modules?environment=env

HTTP/1.1 200 OK
Content-Type: application/json

{
    "modules": [
        {
            "name": "puppetlabs/ntp",
            "version": "6.0.0"
        },
        {
            "name": "puppetlabs/stdlib",
            "version": "4.14.0"
        }
    ],
    "name": "env"
}

Environment does not exist

If you send a request with an environment parameter that doesn't correspond to the name of a directory environment on the server, the server returns an HTTP 404 (Not Found) error:

GET /puppet/v3/environment_modules?environment=doesnotexist

HTTP/1.1 404 Not Found

Could not find environment 'doesnotexist'

No environment given

GET /puppet/v3/environment_modules

HTTP/1.1 400 Bad Request

An environment parameter must be specified

Environment parameter specified with no value

GET /puppet/v3/environment_modules?environment=

HTTP/1.1 400 Bad Request

The environment must be purely alphanumeric, not ''

Environment includes non-alphanumeric characters

If the environment parameter in your request includes any characters that are not A-Z, a-z, 0-9, or _ (underscore), the server returns an HTTP 400 (Bad Request) error:

GET /puppet/v3/environment_modules?environment=bog|us

HTTP/1.1 400 Bad Request

The environment must be purely alphanumeric, not 'bog|us'

No metadata.json file

If your modules do not have a metadata.json file, puppetserver will not be able to determine the version of your module. In this case, puppetserver will return a null value for version in the response body.

Schema

An environment modules response body conforms to the environment modules schema.

Validating your json

If you have a response body that you'd like to validate against the environment_modules.json schema, you can do so using the ruby library json-schema.

First, install the ruby gem to be used:

gem install json-schema

Next, given a json file, you can validate its schema.

Here is a basic json file called example.json:

{
    "modules": [
        {
            "name": "puppetlabs/ntp",
            "version": "6.0.0"
        },
        {
            "name": "puppetlabs/stdlib",
            "version": "4.16.0"
        }
    ],
    "name": "production"
}

Run this command from the root dir of the puppetserver project (or update the path to the json schema file in the command below):

ruby -rjson-schema -e "puts JSON::Validator.validate!('./documentation/puppet-api/v3/environment_modules.json','example.json')"

If the json is a valid schema, the command should output true. Otherwise, the library will print a schema validation error detailing which key or keys validate the schema.

If you have a response that is the entire list of environment modules (i.e. the environment_modules endpoint), you will need to use this command to validate the json schema:

ruby -rjson-schema -e "puts JSON::Validator.validate!('./documentation/puppet-api/v3/environment_modules.json','all.json', :list=>true)"

Authorization

All requests made to the environment modules API are authorized using the Trapperkeeper-based auth.conf.

For more information about the Puppet Server authorization process and configuration settings, see the auth.conf documentation.