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

Examples

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
x-content-type-options: nosniff

Show response body

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