ArangoDB v3.12 is under development and not released yet.

This documentation is not final and potentially incomplete.

HTTP interface for tasks

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

List all 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

[ ]

Get a task

GET /_api/tasks/{id}

fetches one existing task on the server specified by id

Path Parameters

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

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

Create a task

POST /_api/tasks

creates a new task with a generated id

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

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/71807
Show response body

Create a task with ID

PUT /_api/tasks/{id}

Registers a new task with the specified ID.

Not compatible with load balancers.

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

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: 241
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

Delete a task

DELETE /_api/tasks/{id}

Deletes the task identified by id on the server.

Path Parameters

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

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