How to use the REST API Endpoints

Overview

ClusterCockpit offers several REST API Endpoints. While some are integral part of the ClusterCockpit-Stack Workflow (such asstart_job), others are optional. These optional endpoints supplement the functionality of the webinterface with information reachable from scripts or the command line.

Admin Accessible REST API

These endpoints are secured by JWT authentication. As such, all prerequisites applicable to Json Web Tokens apply in this case as well, e.g. private and public key setup.

Endpoints described here should be restricted to administrators only, as they include integral functions.

Admin API Prerequisites

JWT has to be generated by either a dedicated API user (Has only api role) or an Administrator with both admin and api roles.
JWTs have a limited lifetime, i.e. will become invalid after a configurable amount of time (see jwt.max-age config option).
These endpoints are additionally subjected to a configurable IP whitelist (see apiAllowedIPs config option). The config option has to be present with at least the wildcard * as only entry.

Admin API Endpoints and Functions

Endpoint	Method	Request	Description
`/api/users/`	GET	-	Lists all Users
`/api/clusters/`	GET	-	Lists all Clusters
`/api/jobs/start_job/`	POST, PUT	JSON Payload	Starts Job
`/api/jobs/stop_job/`	POST, PUT	JSON Payload	Stops Jobs
`/api/jobs/`	GET	URL-Query Params	Lists Jobs
`/api/jobs/{id}`	POST	$id, JSON Payload	Loads specified job metadata
`/api/jobs/{id}`	GET	$id	Loads specified job with metrics
`/api/jobs/tag_job/{id}`	POST, PATCH	$id, JSON Payload	Tags specified job with tag ids in payload
`/api/jobs/edit_meta/{id}`	POST, PATCH	$id, JSON Payload	Edits meta_data db colums info
`/api/jobs/metrics/{id}`	GET	$id, URL-Query Params	Loads specified jobmetrics for metric and scope params
`/api/jobs/delete_job/`	DELETE	JSON Payload	Deletes job specified in payload
`/api/jobs/delete_job/{id}`	DELETE	$id, JSON Payload	Deletes job specified by db id
`/api/jobs/delete_job_before/{ts}`	DELETE	$ts	Deletes all jobs before specified unix timestamp

User Accessible REST API

These endpoints are secured by JWT authentication. As such, all prerequisites applicable to Json Web Tokens apply in this case as well, e.g. private and public key setup.

Endpoints described here can be used by users to write scripted job analysis for their jobs only.

User API Prerequisites

JWT has to be generated by either a dedicated API user (Has only api role) or an User with additional api role.
JWTs have a limited lifetime, i.e. will become invalid after a configurable amount of time (see jwt.max-age config option).

User API Endpoints and Functions

Endpoint	Method	Request	Description
`/userapi/jobs/`	GET	URL-Query Params	Lists Jobs
`/userapi/jobs/{id}`	POST	$id, JSON Payload	Loads specified job metadata
`/userapi/jobs/{id}`	GET	$id	Loads specified job with metrics
`/userapi/jobs/metrics/{id}`	GET	$id, URL-Query Params	Loads specified jobmetrics for metric and scope params

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.