HTTP tasks Interface

Following you have ArangoDB’s HTTP Interface for Tasks.

There are also some examples provided for every API action.

Fetch all tasks or one task

Retrieves all currently active server tasks

GET /_api/tasks/

fetches all existing tasks on the server

HTTP 200 The list of tasks

  • **: a list of all tasks

Examples

Fetching all tasks

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

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

[ 
  { 
    "id" : "73", 
    "name" : "user-defined task", 
    "created" : 1558048328.7980807, 
    "type" : "periodic", 
    "period" : 1, 
    "offset" : 0.000001, 
    "command" : "(function (params) { (function () {\n        require('@arangodb/foxx/queues/manager').manage();\n      })(params) } )(params);", 
    "database" : "_system" 
  } 
]

Fetch one task with id

Retrieves one currently active server task

GET /_api/tasks/{id}

Path Parameters

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

fetches one existing task on the server specified by id

HTTP 200 The requested task

  • **: The function in question

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 OK
content-type: application/json; charset=utf-8
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 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

Show response body

creates a task

creates a new task

POST /_api/tasks

A JSON object with these properties is required:

  • name: The name of the task

  • command: The JavaScript code to be executed

  • params: The parameters to be passed into command

  • period: number of seconds between the executions

  • offset: Number of seconds initial delay

creates a new task with a generated id

HTTP 200 The task was registered

  • id: A string identifying the task

  • created: The timestamp when this task was created

  • type: 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: this task should run each period seconds

    • offset: time offset in seconds from the created timestamp

    • command: the javascript function for this task

    • database: the database this task belongs to

    • code: The status code, 200 in this case.

    • error: false in this case

    • 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 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

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

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 (required): The id of the task to create

A JSON object with these properties is required:

  • name: The name of the task

  • command: The JavaScript code to be executed

  • params: The parameters to be passed into command

  • period: number of seconds between the executions

  • offset: Number of seconds initial delay

registers a new task with the specified id

Return codes

  • 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 OK
content-type: application/json; charset=utf-8
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 (required): The id of the task to delete.

Deletes the task identified by id on the server.

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

  • code: The status code, 200 in this case.

  • error: false in this case

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

  • code: The status code, 404 in this case.

  • error: true in this case

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

Examples

trying to delete non existing task

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

HTTP/1.1 Not Found
content-type: application/json; charset=utf-8
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 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

Show response body