HTTP Interface for Miscellaneous functions

This is an overview of ArangoDB's HTTP interface for miscellaneous functions.

Return server version

returns the server version number

GET /_api/version

Query Parameters

  • details (optional): If set to true, the response will contain a details attribute with additional information about included components and their versions. The attribute names and internals of the details object may vary depending on platform and ArangoDB version.

Returns the server name and version number. The response is a JSON object with the following attributes:

A json document with these Properties is returned:

HTTP 200

is returned in all cases.

  • version: the server version string. The string has the format "major.minor.sub". major and minor will be numeric, and sub may contain a number or a textual version.
  • details: an optional JSON object with additional details. This is returned only if the details query parameter is set to true in the request.
  • server: will always contain arango

Example:

Return the version information

shell> curl --dump - http://localhost:8529/_api/version

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

{ 
  "server" : "arango", 
  "version" : "3.3.3", 
  "license" : "community" 
}

Example:

Return the version information with details

shell> curl --dump - http://localhost:8529/_api/version?details=true

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

{ 
  "server" : "arango", 
  "version" : "3.3.3", 
  "license" : "community", 
  "details" : { 
    "architecture" : "64bit", 
    "arm" : "false", 
    "asan" : "false", 
    "asm-crc32" : "true", 
    "assertions" : "true", 
    "boost-version" : "1.62.0", 
    "build-date" : "2018-01-25 19:30:05", 
    "build-repository" : "heads/3.3.3-0-gd1ca58310e-dirty", 
    "compiler" : "gcc [7.2.0]", 
    "cplusplus" : "201103", 
    "debug" : "false", 
    "endianness" : "little", 
    "failure-tests" : "false", 
    "fd-client-event-handler" : "poll", 
    "fd-setsize" : "1024", 
    "full-version-string" : "ArangoDB 3.3.3 [linux] 64bit maintainer mode, using jemalloc, VPack 0.1.30, RocksDB 5.6.0, ICU 58.1, V8 5.7.492.77, OpenSSL 1.0.2g  1 Mar 2016", 
    "icu-version" : "58.1", 
    "jemalloc" : "true", 
    "maintainer-mode" : "true", 
    "openssl-version" : "OpenSSL 1.0.2g  1 Mar 2016", 
    "platform" : "linux", 
    "reactor-type" : "epoll", 
    "rocksdb-version" : "5.6.0", 
    "server-version" : "3.3.3", 
    "sizeof int" : "4", 
    "sizeof void*" : "8", 
    "sse42" : "false", 
    "unaligned-access" : "true", 
    "v8-version" : "5.7.492.77", 
    "vpack-version" : "0.1.30", 
    "zlib-version" : "1.2.11", 
    "mode" : "server", 
    "host" : "c54ebb83e5eb4257b9e0f7201ba87ded" 
  } 
}

Return Codes

  • 200: is returned in all cases.

Response Body

  • version: the server version string. The string has the format "major.minor.sub". major and minor will be numeric, and sub may contain a number or a textual version.
  • details: an optional JSON object with additional details. This is returned only if the details query parameter is set to true in the request.
  • server: will always contain arango
shell> curl --dump - http://localhost:8529/_api/version

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

Return the version information with details

shell> curl --dump - http://localhost:8529/_api/version?details=true

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

Return server database engine type

returns the engine the type the server is running with

GET /_api/engine

Returns the storage engine the server is configured to use. The response is a JSON object with the following attributes:

A json document with these Properties is returned:

HTTP 200

is returned in all cases.

  • name: will be mmfiles or rocksdb

Example:

Return the active storage engine

shell> curl --dump - http://localhost:8529/_api/engine

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

{ 
  "name" : "mmfiles", 
  "supports" : { 
    "dfdb" : true, 
    "indexes" : [ 
      "primary", 
      "edge", 
      "hash", 
      "skiplist", 
      "persistent", 
      "geo", 
      "fulltext" 
    ] 
  } 
}

Return Codes

  • 200: is returned in all cases.

Response Body

  • name: will be mmfiles or rocksdb
shell> curl --dump - http://localhost:8529/_api/engine

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

Flushes the write-ahead log

Sync the WAL to disk.

PUT /_admin/wal/flush

Path Parameters

  • waitForSync (optional): Whether or not the operation should block until the not-yet synchronized data in the write-ahead log was synchronized to disk.
  • waitForCollector (optional): Whether or not the operation should block until the data in the flushed log has been collected by the write-ahead log garbage collector. Note that setting this option to true might block for a long time if there are long-running transactions and the write-ahead log garbage collector cannot finish garbage collection.

Flushes the write-ahead log. By flushing the currently active write-ahead logfile, the data in it can be transferred to collection journals and datafiles. This is useful to ensure that all data for a collection is present in the collection journals and datafiles, for example, when dumping the data of a collection.

Return Codes

  • 200: Is returned if the operation succeeds.
  • 405: is returned when an invalid HTTP method is used.

Retrieves the configuration of the write-ahead log

fetch the current configuration.

GET /_admin/wal/properties

Retrieves the configuration of the write-ahead log. The result is a JSON object with the following attributes:

  • allowOversizeEntries: whether or not operations that are bigger than a single logfile can be executed and stored
  • logfileSize: the size of each write-ahead logfile
  • historicLogfiles: the maximum number of historic logfiles to keep
  • reserveLogfiles: the maximum number of reserve logfiles that ArangoDB allocates in the background
  • syncInterval: the interval for automatic synchronization of not-yet synchronized write-ahead log data (in milliseconds)
  • throttleWait: the maximum wait time that operations will wait before they get aborted if case of write-throttling (in milliseconds)
  • throttleWhenPending: the number of unprocessed garbage-collection operations that, when reached, will activate write-throttling. A value of 0 means that write-throttling will not be triggered.

Example:

shell> curl --dump - http://localhost:8529/_admin/wal/properties

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

{ 
  "allowOversizeEntries" : true, 
  "logfileSize" : 33554432, 
  "historicLogfiles" : 10, 
  "reserveLogfiles" : 3, 
  "syncInterval" : 100, 
  "throttleWait" : 15000, 
  "throttleWhenPending" : 0 
}

Return Codes

  • 200: Is returned if the operation succeeds.
  • 405: is returned when an invalid HTTP method is used.

Configures the write-ahead log

configure parameters of the wal

PUT /_admin/wal/properties

Configures the behavior of the write-ahead log. The body of the request must be a JSON object with the following attributes:

  • allowOversizeEntries: whether or not operations that are bigger than a single logfile can be executed and stored
  • logfileSize: the size of each write-ahead logfile
  • historicLogfiles: the maximum number of historic logfiles to keep
  • reserveLogfiles: the maximum number of reserve logfiles that ArangoDB allocates in the background
  • throttleWait: the maximum wait time that operations will wait before they get aborted if case of write-throttling (in milliseconds)
  • throttleWhenPending: the number of unprocessed garbage-collection operations that, when reached, will activate write-throttling. A value of 0 means that write-throttling will not be triggered.

Specifying any of the above attributes is optional. Not specified attributes will be ignored and the configuration for them will not be modified.

Example:

shell> curl -X PUT --data-binary @- --dump - http://localhost:8529/_admin/wal/properties <<EOF
{ 
  "logfileSize" : 33554432, 
  "allowOversizeEntries" : true 
}
EOF

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

{ 
  "allowOversizeEntries" : true, 
  "logfileSize" : 33554432, 
  "historicLogfiles" : 10, 
  "reserveLogfiles" : 3, 
  "syncInterval" : 100, 
  "throttleWait" : 15000, 
  "throttleWhenPending" : 0 
}

Return Codes

  • 200: Is returned if the operation succeeds.
  • 405: is returned when an invalid HTTP method is used.

Returns information about the currently running transactions

returns information about the currently running transactions

GET /_admin/wal/transactions

Returns information about the currently running transactions. The result is a JSON object with the following attributes:

  • runningTransactions: number of currently running transactions
  • minLastCollected: minimum id of the last collected logfile (at the start of each running transaction). This is null if no transaction is running.
  • minLastSealed: minimum id of the last sealed logfile (at the start of each running transaction). This is null if no transaction is running.

Example:

shell> curl --dump - http://localhost:8529/_admin/wal/transactions

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

{ 
  "runningTransactions" : 5, 
  "minLastCollected" : 85, 
  "minLastSealed" : null 
}

Return Codes

  • 200: Is returned if the operation succeeds.
  • 405: is returned when an invalid HTTP method is used.

Return system time

Get the current time of the system

GET /_admin/time

The call returns an object with the attribute time. This contains the current system time as a Unix timestamp with microsecond precision.

Return Codes

  • 200: Time was returned successfully.

Return current request

Send back what was sent in, headers, post body etc.

GET /_admin/echo

The call returns an object with the following attributes:

  • headers: object with HTTP headers received

  • requestType: the HTTP request method (e.g. GET)

  • parameters: object with query parameters received

Return Codes

  • 200: Echo was returned successfully.

Return current request and continues

Send back what was sent in, headers, post body etc.

GET /_admin/long_echo

The call returns an object with the following attributes:

  • headers: object with HTTP headers received

  • requestType: the HTTP request method (e.g. GET)

  • parameters: object with query parameters received

Return Codes

  • 200: Echo was returned successfully.

Return the required version of the database

returns the version of the database.

GET /_admin/database/target-version

Returns the database-version that this server requires. The version is returned in the version attribute of the result.

Return Codes

  • 200: Is returned in all cases.

Initiate shutdown sequence

initiates the shutdown sequence

DELETE /_admin/shutdown

This call initiates a clean shutdown sequence. Requires administrive privileges

Return Codes

  • 200: is returned in all cases.

Runs tests on server

show the available unittests on the server.

POST /_admin/test

Request Body (required)

A JSON object containing an attribute tests which lists the files containing the test suites.

Executes the specified tests on the server and returns an object with the test results. The object has an attribute "error" which states whether any error occurred. The object also has an attribute "passed" which indicates which tests passed and which did not.

Execute program

Execute a script on the server.

POST /_admin/execute

Request Body (required)

The body to be executed.

Executes the javascript code in the body on the server as the body of a function with no arguments. If you have a return statement then the return value you produce will be returned as content type application/json. If the parameter returnAsJSON is set to true, the result will be a JSON object describing the return value directly, otherwise a string produced by JSON.stringify will be returned.

Note that this API endpoint will only be present if the server was started with the option --javascript.allow-admin-execute true.

The default value of this option is false, which disables the execution of user-defined code and disables this API endpoint entirely. This is also the recommended setting for production.

© ArangoDB - the native multi-model NoSQL database