HTTP interface for tasks

The HTTP API for tasks lets you can manage the periodic or timed execution of server-side JavaScript code

Fetch all tasks or one task

Retrieves all currently active server tasks

GET /_api/tasks/

fetches all existing tasks on the server

Responses

HTTP 200: The list of tasks

  • (array): a list of all tasks

    • name (string): A user-friendly name for the task.

    • id (string): A string identifying the task.

    • created (number): The timestamp when this task was created.

    • type (string): What type of task is this [ periodic, timed]
      • periodic are tasks that repeat periodically
      • timed are tasks that execute once at a specific time

    • period (number): This task should run each period seconds.

    • offset (number): Time offset in seconds from the created timestamp.

    • command (string): The JavaScript function for this task.

    • database (string): The database this task belongs to.

Examples

Fetching all tasks

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/tasks

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 2
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

[ ]

Fetch one task with id

Retrieves one currently active server task

GET /_api/tasks/{id}

Path Parameters

  • id (string, required): The id of the task to fetch.

fetches one existing task on the server specified by id

Responses

HTTP 200: The requested task

  • name (string): A user-friendly name for the task.

  • id (string): A string identifying the task.

  • created (number): The timestamp when this task was created.

  • type (string): What type of task is this [ periodic, timed]
    • periodic are tasks that repeat periodically
    • timed are tasks that execute once at a specific time

  • period (number): This task should run each period seconds.

  • offset (number): Time offset in seconds from the created timestamp.

  • command (string): The JavaScript function for this task.

  • database (string): The database this task belongs to.

Examples

Fetching a single task by its id

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/tasks <<EOF
{"id":"testTask","command":"console.log('Hello from task!');","offset":10000}
EOF

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/tasks/testTask

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 206
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

Trying to fetch a non-existing task

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/tasks/non-existing-task

HTTP/1.1 404 Not Found
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 73
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

creates a task

creates a new task

POST /_api/tasks

Request Body

  • name (string, required): The name of the task

  • command (string, required): The JavaScript code to be executed

  • params (string, required): The parameters to be passed into command

  • period (integer, optional): number of seconds between the executions

  • offset (integer, optional): Number of seconds initial delay

creates a new task with a generated id

Responses

HTTP 200: The task was registered

  • id (string): A string identifying the task

  • created (number): The timestamp when this task was created

  • type (string): What type of task is this [ periodic, timed]
    • periodic are tasks that repeat periodically
    • timed are tasks that execute once at a specific time

  • period (number): this task should run each period seconds

  • offset (number): time offset in seconds from the created timestamp

  • command (string): the javascript function for this task

  • database (string): the database this task belongs to

  • code (number): The status code, 200 in this case.

  • error (boolean): false in this case

HTTP 400: If the post body is not accurate, a HTTP 400 is returned.

Examples

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/tasks/ <<EOF
{ 
  "name" : "SampleTask", 
  "command" : "(function(params) { require('@arangodb').print(params); })(params)", 
  "params" : { 
    "foo" : "bar", 
    "bar" : "foo" 
  }, 
  "period" : 2 
}
EOF

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 240
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/tasks/70766
Show response body

creates a task with id

registers a new task with a pre-defined id; not compatible with load balancers

PUT /_api/tasks/{id}

Path Parameters

  • id (string, required): The id of the task to create

Request Body

  • name (string, required): The name of the task

  • command (string, required): The JavaScript code to be executed

  • params (string, required): The parameters to be passed into command

  • period (integer, optional): number of seconds between the executions

  • offset (integer, optional): Number of seconds initial delay

registers a new task with the specified id

Responses

HTTP 400: If the task id already exists or the rest body is not accurate, HTTP 400 is returned.

Examples

shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/tasks/sampleTask <<EOF
{ 
  "id" : "SampleTask", 
  "name" : "SampleTask", 
  "command" : "(function(params) { require('@arangodb').print(params); })(params)", 
  "params" : { 
    "foo" : "bar", 
    "bar" : "foo" 
  }, 
  "period" : 2 
}
EOF

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 245
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

deletes the task with id

deletes one currently active server task

DELETE /_api/tasks/{id}

Path Parameters

  • id (string, required): The id of the task to delete.

Deletes the task identified by id on the server.

Responses

HTTP 200: If the task was deleted, HTTP 200 is returned.

  • code (number): The status code, 200 in this case.

  • error (boolean): false in this case

HTTP 404: If the task id is unknown, then an HTTP 404 is returned.

  • code (number): The status code, 404 in this case.

  • error (boolean): true in this case

  • errorMessage (string): A plain text message stating what went wrong.

Examples

Try to delete a non-existent task:

shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/tasks/NoTaskWithThatName

HTTP/1.1 404 Not Found
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 73
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

Remove existing task:

shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/tasks/SampleTask

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 26
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body
❮  Jobs

© ArangoDB - Graph and Beyond