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 dask
- 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 dask
- 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 --dump - http://localhost:8529/_api/tasks
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
[
{
"id" : "72",
"name" : "user-defined task",
"created" : 1530713370.4460926,
"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 dask
- 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 dask
- 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 --data-binary @- --dump - http://localhost:8529/_api/tasks <<EOF
{"id":"testTask","command":"console.log('Hello from task!');","offset":10000}
EOF
shell> curl --dump - http://localhost:8529/_api/tasks/testTask
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
{
"id" : "testTask",
"name" : "user-defined task",
"created" : 1530713425.236918,
"type" : "timed",
"offset" : 10000,
"command" : "(function (params) { console.log('Hello from task!'); } )(params);",
"database" : "_system",
"error" : false,
"code" : 200
}
shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/tasks <<EOF
{"id":"testTask","command":"console.log('Hello from task!');","offset":10000}
EOF
shell> curl --dump - http://localhost:8529/_api/tasks/testTask
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Trying to fetch a non-existing task
shell> curl --dump - http://localhost:8529/_api/tasks/non-existing-task
HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
{
"error" : true,
"code" : 404,
"errorNum" : 1852,
"errorMessage" : "task not found"
}
shell> curl --dump - http://localhost:8529/_api/tasks/non-existing-task
HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
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 dask
- 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 dask
- 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 --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; charset=utf-8
x-content-type-options: nosniff
{
"id" : "13883",
"name" : "SampleTask",
"created" : 1530713425.2025268,
"type" : "periodic",
"period" : 2,
"offset" : 0,
"command" : "(function (params) { (function(params) { require('@arangodb').print(params); })(params) } )(params);",
"database" : "_system",
"error" : false,
"code" : 200
}
shell> curl -X DELETE --dump - http://localhost:8529/_api/tasks/13883
shell> curl -X POST --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; charset=utf-8
x-content-type-options: nosniff
creates a task with id
registers a new task with a pre-defined id
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 --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; charset=utf-8
x-content-type-options: nosniff
{
"id" : "sampleTask",
"name" : "SampleTask",
"created" : 1530713425.2462006,
"type" : "periodic",
"period" : 2,
"offset" : 0,
"command" : "(function (params) { (function(params) { require('@arangodb').print(params); })(params) } )(params);",
"database" : "_system",
"error" : false,
"code" : 200
}
shell> curl -X DELETE --dump - http://localhost:8529/_api/tasks/sampleTask
shell> curl -X PUT --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; charset=utf-8
x-content-type-options: nosniff
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 --dump - http://localhost:8529/_api/tasks/NoTaskWithThatName
HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
{
"error" : true,
"code" : 404,
"errorNum" : 1852,
"errorMessage" : "task not found"
}
shell> curl -X DELETE --dump - http://localhost:8529/_api/tasks/NoTaskWithThatName
HTTP/1.1 404 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Remove existing Task
shell> curl -X DELETE --data-binary @- --dump - http://localhost:8529/_api/tasks/SampleTaskshell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/tasks/SampleTaskshell> curl -X DELETE --dump - http://localhost:8529/_api/tasks/SampleTask
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
{
"error" : false,
"code" : 200
}