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

Example:

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" : "statistics-gc", 
    "name" : "statistics-gc", 
    "created" : 1516907609.406109, 
    "type" : "periodic", 
    "period" : 450, 
    "offset" : 406.020662, 
    "command" : "(function (params) { require('@arangodb/statistics').garbageCollector(); } )(params);", 
    "database" : "_system" 
  }, 
  { 
    "id" : "statistics-average-collector", 
    "name" : "statistics-average-collector", 
    "created" : 1516907609.4059584, 
    "type" : "periodic", 
    "period" : 900, 
    "offset" : 20, 
    "command" : "(function (params) { require('@arangodb/statistics').historianAverage(); } )(params);", 
    "database" : "_system" 
  }, 
  { 
    "id" : "statistics-collector", 
    "name" : "statistics-collector", 
    "created" : 1516907609.4056144, 
    "type" : "periodic", 
    "period" : 10, 
    "offset" : 1, 
    "command" : "(function (params) { require('@arangodb/statistics').historian(); } )(params);", 
    "database" : "_system" 
  }, 
  { 
    "id" : "84", 
    "name" : "user-defined task", 
    "created" : 1516907599.4534233, 
    "type" : "periodic", 
    "period" : 1, 
    "offset" : 0.000001, 
    "command" : "(function (params) { (function () {
        require('@arangodb/foxx/queues/manager').manage();
      })(params) } )(params);", 
    "database" : "_system" 
  } 
]
  • 200: The list of tasks

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" : "statistics-gc", 
    "name" : "statistics-gc", 
    "created" : 1516907609.406109, 
    "type" : "periodic", 
    "period" : 450, 
    "offset" : 406.020662, 
    "command" : "(function (params) { require('@arangodb/statistics').garbageCollector(); } )(params);", 
    "database" : "_system" 
  }, 
  { 
    "id" : "statistics-average-collector", 
    "name" : "statistics-average-collector", 
    "created" : 1516907609.4059584, 
    "type" : "periodic", 
    "period" : 900, 
    "offset" : 20, 
    "command" : "(function (params) { require('@arangodb/statistics').historianAverage(); } )(params);", 
    "database" : "_system" 
  }, 
  { 
    "id" : "statistics-collector", 
    "name" : "statistics-collector", 
    "created" : 1516907609.4056144, 
    "type" : "periodic", 
    "period" : 10, 
    "offset" : 1, 
    "command" : "(function (params) { require('@arangodb/statistics').historian(); } )(params);", 
    "database" : "_system" 
  }, 
  { 
    "id" : "84", 
    "name" : "user-defined task", 
    "created" : 1516907599.4534233, 
    "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 tasks on the server specified by id

Example:

Fetching a single task by its id

shell> curl --dump - http://localhost:8529/_api/tasks/statistics-average-collector

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

{ 
  "id" : "statistics-average-collector", 
  "name" : "statistics-average-collector", 
  "created" : 1516907609.4059584, 
  "type" : "periodic", 
  "period" : 900, 
  "offset" : 20, 
  "command" : "(function (params) { require('@arangodb/statistics').historianAverage(); } )(params);", 
  "database" : "_system", 
  "error" : false, 
  "code" : 200 
}

Example:

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" 
}
  • 200: The requested task

Examples

Fetching a single task by its id

shell> curl --dump - http://localhost:8529/_api/tasks/statistics-average-collector

HTTP/1.1 200 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 --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
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

Example:

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" : "12983", 
  "name" : "SampleTask", 
  "created" : 1516907628.2369483, 
  "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/12983

Return Codes

  • 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
show response body

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

Example:

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" : 1516907628.2489061, 
  "type" : "periodic", 
  "period" : 2, 
  "offset" : 0, 
  "command" : "(function (params) { (function(params) { require('@arangodb').print(params); })(params) } )(params);", 
  "database" : "_system", 
  "error" : false, 
  "code" : 200 
}

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
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.

Example:

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" 
}

Example:

Remove existing Task

shell> 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 
}

Return Codes

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

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
show response body

Remove existing Task

shell> 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 
}

© ArangoDB - the native multi-model NoSQL database