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 A json document with these Properties is returned:

The list of tasks

[

  • name: The fully qualified name of the user function
  • created: The timestamp when this task was created
  • database: the database this task belongs to
  • period: this task should run each period seconds
  • command: the javascript function for this task
  • offset: time offset in seconds from the created timestamp
  • 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
  • id: A string identifying the task ]
  • 200: The list of tasks

Response Body [

  • name: The fully qualified name of the user function
  • database: the database this task belongs to
  • created: The timestamp when this task was created
  • period: this task should run each period seconds
  • command: the javascript function for this task
  • offset: time offset in seconds from the created timestamp
  • 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
  • id: A string identifying the task ]

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" : "71", 
    "name" : "user-defined task", 
    "created" : 1551217541.0000262, 
    "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}

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

fetches one existing task on the server specified by id

HTTP 200 A json document with these Properties is returned:

The requested task

  • name: The fully qualified name of the user function
  • created: The timestamp when this task was created
  • database: the database this task belongs to
  • period: this task should run each period seconds
  • command: the javascript function for this task
  • offset: time offset in seconds from the created timestamp
  • 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
  • id: A string identifying the task

  • 200: The requested task

Response Body

  • name: The fully qualified name of the user function
  • database: the database this task belongs to
  • created: The timestamp when this task was created
  • period: this task should run each period seconds
  • command: the javascript function for this task
  • offset: time offset in seconds from the created timestamp
  • 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
  • id: A string identifying the task

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:

  • params: The parameters to be passed into command
  • offset: Number of seconds initial delay
  • command: The JavaScript code to be executed
  • name: The name of the task
  • period: number of seconds between the executions

creates a new task with a generated id

HTTP 200 A json document with these Properties is returned:

The task was registered

  • code: The status code, 200 in this case.
  • created: The timestamp when this task was created
  • database: the database this task belongs to
  • period: this task should run each period seconds
  • command: the javascript function for this task
  • error: false in this case
  • offset: time offset in seconds from the created timestamp
  • 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
  • id: A string identifying the task

Return Codes

  • 200: The task was registered

Response Body

  • code: The status code, 200 in this case.
  • database: the database this task belongs to
  • created: The timestamp when this task was created
  • period: this task should run each period seconds
  • offset: time offset in seconds from the created timestamp
  • command: the javascript function for this task
  • error: false in this case
  • 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
  • id: A string identifying the task

  • 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/106314

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}

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

A JSON object with these properties is required:

  • params: The parameters to be passed into command
  • offset: Number of seconds initial delay
  • command: The JavaScript code to be executed
  • name: The name of the task
  • period: number of seconds between the executions

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}

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

Deletes the task identified by id on the server.

HTTP 200 A json document with these Properties is returned:

If the task was deleted, HTTP 200 is returned.

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

HTTP 404 A json document with these Properties is returned:

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

  • errorMessage: A plain text message stating what went wrong.
  • code: The status code, 404 in this case.
  • error: true in this case

Return Codes

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

Response Body

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

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

Response Body

  • errorMessage: A plain text message stating what went wrong.
  • code: The status code, 404 in this case.
  • error: true in this case

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