Jobs

Nick provides a jobs system to manage long-running tasks asynchronously. Jobs can be created, listed, inspected, deleted, aborted, and retried.

Verb	URL	Action
GET	/@jobs	List all jobs
GET	/@jobs/{id}	Get a specific job
DELETE	/@jobs/{id}	Delete a job
POST	/@jobs/{id}/abort	Abort a running job
POST	/@jobs/{id}/retry	Retry a failed job

Job schema

A job object has the following properties:

Property	Type	Description
uuid	string	UUID of the job
title	string	Human-readable title
description	string	Human-readable description
params	object	Parameters passed to the job
actor	string	User who created the job
created	datetime	Timestamp when the job was created
started	datetime or null	Timestamp when the job started
finished	datetime or null	Timestamp when the job finished
status	string	Status: created, running, completed, failed, or aborted
result	object	Result data produced by the job

List all jobs

To retrieve all jobs, send a GET request to the /@jobs endpoint:

GET /@jobs HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

Or use the client directly:

import { Client } from '@robgietema/nick';

const cli = Client.initialize({ apiPath: 'http://localhost:8080' });
const login = await cli.login({
  data: { login: 'admin', password: 'admin' },
});

const { data } = await cli.getJobs({
  token: login.data.token,
});

Response:

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

[
  {
    "uuid": "a2fe7e07-d54b-435b-9cb0-e12f1f80a589",
    "title": "Reindex Events",
    "description": "Reindex all events",
    "params": {
      "scheduled_job": "reindex-events",
      "action": "reindex",
      "type": "Event"
    },
    "actor": "admin",
    "created": "2022-04-02T20:00:00.000Z",
    "started": null,
    "finished": null,
    "status": "created",
    "result": {}
  }
]

Get a specific job

To retrieve a single job by its UUID, send a GET request to the /@jobs/{id} endpoint:

GET /@jobs/a2fe7e07-d54b-435b-9cb0-e12f1f80a589 HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

Or use the client directly:

import { Client } from '@robgietema/nick';

const cli = Client.initialize({ apiPath: 'http://localhost:8080' });
const login = await cli.login({
  data: { login: 'admin', password: 'admin' },
});

const { data } = await cli.getJob({
  token: login.data.token,
  params: { id: 'a2fe7e07-d54b-435b-9cb0-e12f1f80a589' },
});

Response:

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

{
  "@id": "http://localhost:8080/@jobs/a2fe7e07-d54b-435b-9cb0-e12f1f80a589",
  "uuid": "a2fe7e07-d54b-435b-9cb0-e12f1f80a589",
  "title": "Reindex Events",
  "description": "Reindex all events",
  "params": {
    "scheduled_job": "reindex-events",
    "action": "reindex",
    "type": "Event"
  },
  "actor": "admin",
  "created": "2022-04-02T20:00:00.000Z",
  "started": null,
  "finished": null,
  "status": "created",
  "result": {}
}

Delete a job

To delete a job, send a DELETE request to the /@jobs/{id} endpoint:

DELETE /@jobs/a2fe7e07-d54b-435b-9cb0-e12f1f80a589 HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

Or use the client directly:

import { Client } from '@robgietema/nick';

const cli = Client.initialize({ apiPath: 'http://localhost:8080' });
const login = await cli.login({
  data: { login: 'admin', password: 'admin' },
});

const { data } = await cli.deleteJob({
  token: login.data.token,
  params: {
    id: 'a2fe7e07-d54b-435b-9cb0-e12f1f80a589',
  },
});

Response:

HTTP/1.1 204 No Content

Abort a job

To abort a running job, send a POST request to the /@jobs/{id}/abort endpoint:

POST /@jobs/a2fe7e07-d54b-435b-9cb0-e12f1f80a589/abort HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

Or use the client directly:

import { Client } from '@robgietema/nick';

const cli = Client.initialize({ apiPath: 'http://localhost:8080' });
const login = await cli.login({
  data: { login: 'admin', password: 'admin' },
});

const { data } = await cli.abortJob({
  token: login.data.token,
  params: {
    id: 'a2fe7e07-d54b-435b-9cb0-e12f1f80a589',
  },
});

Response:

HTTP/1.1 204 No Content

Retry a job

To retry a failed job, send a POST request to the /@jobs/{id}/retry endpoint:

POST /@jobs/a2fe7e07-d54b-435b-9cb0-e12f1f80a589/retry HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

Or use the client directly:

import { Client } from '@robgietema/nick';

const cli = Client.initialize({ apiPath: 'http://localhost:8080' });
const login = await cli.login({
  data: { login: 'admin', password: 'admin' },
});

const { data } = await cli.retryJob({
  token: login.data.token,
  params: {
    id: 'a2fe7e07-d54b-435b-9cb0-e12f1f80a589',
  },
});

Response:

HTTP/1.1 204 No Content