ArangoDB v3.4 reached End of Life (EOL) and is no longer supported.

This documentation is outdated. Please see the most recent version here: Latest Docs

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:

HTTP 200 is returned in all cases.

  • server: will always contain arango

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

    • architecture: The CPU architecture, i.e. 64bit

    • arm: false - this is not running on an ARM cpu

    • asan: has this been compiled with the asan address sanitizer turned on? (should be false)

    • asm-crc32: do we have assembler implemented CRC functions?

    • assertions: do we have assertions compiled in (=> developer version)

    • boost-version: which boost version do we bind

    • build-date: the date when this binary was created

    • build-repository: reference to the git-ID this was compiled from

    • compiler: which compiler did we use

    • cplusplus: C++ standards version

    • debug: false for production binaries

    • endianness: currently only little is supported

    • failure-tests: false for production binaries (the facility to invoke fatal errors is disabled)

    • fd-client-event-handler: which method do we use to handle fd-sets, poll should be here on linux.

    • fd-setsize: if not poll the fd setsize is valid for the maximum number of filedescriptors

    • full-version-string: The full version string

    • icu-version: Which version of ICU do we bundle

    • jemalloc: true if we use jemalloc

    • maintainer-mode: false if this is a production binary

    • openssl-version: which openssl version do we link?

    • platform: the host os - linux, windows or darwin

    • reactor-type: epoll TODO

    • rocksdb-version: the rocksdb version this release bundles

    • server-version: the ArangoDB release version

    • sizeof int: number of bytes for integers

    • sizeof void: number of bytes for *void pointers

    • sse42: do we have a SSE 4.2 enabled cpu?

    • unaligned-access: does this system support unaligned memory access?

    • v8-version: the bundled V8 javascript engine version

    • vpack-version: the version of the used velocypack implementation

    • zlib-version: the version of the bundled zlib

    • mode: the mode we’re runnig as - one of [server, console, script]

    • host: the host ID

Examples

Return the version information

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

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

Return the version information with details

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/version?details=true

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

HTTP 200 is returned in all cases.

  • name: will be mmfiles or rocksdb

Examples

Return the active storage engine with the MMFiles storage engine in use:

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

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

Return the active storage engine with the RocksDB storage engine in use:

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

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

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

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.

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.

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.

HTTP 200 Time was returned successfully.

  • error: boolean flag to indicate whether an error occurred (false in this case)

  • code: the HTTP status code

  • time: The current system time as a Unix timestamp with microsecond precision of the server

Return current request

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

POST /_admin/echo

Request Body (object)

The body can be any type and is simply forwarded.

The call returns an object with the servers request information

HTTP 200 Echo was returned successfully.

  • authorized: whether the session is authorized

  • user: the currently user that sent this request

  • database: the database this request was executed on

  • url: the raw request URL

  • protocol: the transport, one of [‘http’, ‘https’, ‘velocystream’]

  • server:

    • address: the bind address of the endpoint this request was sent to

    • port: the port this request was sent to

  • client: attributes of the client connection

    • address: the ip address of the client

    • port: port of the client side of the tcp connection

    • id: a server generated id

  • internals: contents of the server internals struct

  • prefix: prefix of the database

  • headers: the list of the HTTP headers you sent

  • requestType: In this case POST, if you use another HTTP-Verb, you will se that (GET/DELETE, …)

  • requestBody: stringified version of the POST body we sent

  • parameters: Object containing the query parameters

  • cookies: list of the cookies you sent

  • suffix:

  • rawSuffix:

  • path: relative path of this request

  • rawRequestBody: List of digits of the sent characters

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, OK will be returned in the result buffer on success.

Execute program

Execute a script on the server.

POST /_admin/execute

Request Body (string)

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.

Return codes

  • 200: is returned when everything went well, or if a timeout occurred. In the latter case a body of type application/json indicating the timeout is returned. depending on returnAsJSON this is a json object or a plain string.

  • 403: is returned if ArangoDB is not running in cluster mode.

  • 404: is returned if ArangoDB was not compiled for cluster operation.

Return status information

returns status information of the server.

GET /_admin/status

Returns status information about the server.

This is intended for manual use by the support and should never be used for monitoring or automatic tests. The results are subject to change without notice.

The call returns an object with the following attributes:

  • server: always arango.

  • license: either community or enterprise.

  • version: the server version as string.

  • mode : either server or console.

  • host: the hostname, see ServerState.

  • serverInfo.role: either SINGLE, COORDINATOR, PRIMARY, AGENT.

  • serverInfo.writeOpsEnabled: boolean, true if writes are enabled.

  • serverInfo.maintenance: boolean, true if maintenace mode is enabled.

  • agency.endpoints: a list of possible agency endpoints.

An agent, coordinator or primary will also have

  • serverInfo.persistedId: the persisted ide, e. g. “CRDN-e427b441-5087-4a9a-9983-2fb1682f3e2a”.

A coordinator or primary will also have

  • serverInfo.state: SERVING

  • serverInfo.address: the address of the server, e. g. tcp://[::1]:8530.

  • serverInfo.serverId: the server ide, e. g. “CRDN-e427b441-5087-4a9a-9983-2fb1682f3e2a”.

A coordinator will also have

  • coordinator.foxxmaster: the server id of the foxx master.

  • coordinator.isFoxxmaster: boolean, true if the server is the foxx master.

An agent will also have

  • agent.id: server id of this agent.

  • agent.leaderId: server id of the leader.

  • agent.leading: boolean, true if leading.

  • agent.endpoint: the endpoint of this agent.

  • agent.term: current term number.

Return codes

  • 200: Status information was returned successfully.
❮  Agency

© ArangoDB - the native multi-model NoSQL database