OpenVox Server: Puppet API: Tasks

The tasks API provides access to task information stored in modules. Tasks are files stored in tasks subdirectory of a module. A task consists of an executable file, with an optional metadata file with the same name with an added ‘.json’ extension. For example, the “install” task in a module “apache” could consist of the executable file install.rb and the metadata file install.json. This task would have the display name “apache::install”.

Note: Tasks file contents in versioned code can be retrieved using the static_file_content endpoint.

Does not return entries for task files with invalid names

A task file name has the same restriction as Puppet type names and must match the regular expression \A[a-z][a-z0-9_]*\z (excluding extensions).

Returns entries for tasks with no executable files

A task will be listed if only metadata for it exists. How many files are associated with a task can be found by querying that task’s details.

Does not read files

This endpoint will not parse metadata or read any other files, only file names.

Uses application/json Content-Type

The Content-Type in the response to an task API query is application/json.

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

Making a request with no query parameters is not supported and returns an HTTP 400 (Bad Request) response.

Supported HTTP Methods

GET

Supported Formats

JSON

Query Parameters

Provide one parameter to the GET request:

• environment: Only the task information pertaining to the specified environment will be returned for the call.

Responses

GET request with results

GET /puppet/v3/tasks?environment=env

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

[
  {
    "name":"apache::install",
    "environment":[
      {
        "name":"env",
        "code_id":null
      }
    ]
  },
  {
    "name":"dashboard::configure",
    "environment":[
      {
        "name":"env",
        "code_id":null
      }
    ]
  }
]

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/tasks?environment=doesnotexist

HTTP/1.1 404 Not Found

Could not find environment 'doesnotexist'

No environment given

GET /puppet/v3/tasks

HTTP/1.1 400 Bad Request

You must specify an environment parameter.

Environment parameter specified with no value

GET /puppet/v3/tasks?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/tasks?environment=bog|us

HTTP/1.1 400 Bad Request

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

Schema

A tasks response body conforms to the tasks schema.

Authorization

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

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