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 (boolean, 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:

Responses

HTTP 200: is returned in all cases.

  • server (string): will always contain arango

  • version (string): 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 (object): an optional JSON object with additional details. This is returned only if the details query parameter is set to true in the request.

    • architecture (string): The CPU architecture, i.e. 64bit

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

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

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

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

    • boost-version (string): which boost version do we bind

    • build-date (string): the date when this binary was created

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

    • compiler (string): which compiler did we use

    • cplusplus (string): C++ standards version

    • debug (string): false for production binaries

    • endianness (string): currently only little is supported

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

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

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

    • full-version-string (string): The full version string

    • icu-version (string): Which version of ICU do we bundle

    • jemalloc (string): true if we use jemalloc

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

    • openssl-version (string): which openssl version do we link?

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

    • reactor-type (string): epoll TODO

    • rocksdb-version (string): the rocksdb version this release bundles

    • server-version (string): the ArangoDB release version

    • sizeof int (string): number of bytes for integers

    • sizeof void* (string): number of bytes for void pointers

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

    • unaligned-access (string): does this system support unaligned memory access?

    • v8-version (string): the bundled V8 javascript engine version

    • vpack-version (string): the version of the used velocypack implementation

    • zlib-version (string): the version of the bundled zlib

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

    • host (string): the host ID

Examples

Return the version information

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

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 60
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
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 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 1822
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
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:

Responses

HTTP 200: is returned in all cases.

  • name (string): 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 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 201
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
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.

Responses

HTTP 200: Time was returned successfully.

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

  • code (integer): the HTTP status code

  • time (number): 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, required)

The body can be any type and is simply forwarded.

The call returns an object with the servers request information

Responses

HTTP 200: Echo was returned successfully.

  • authorized (boolean): Whether the session is authorized

  • user (string): The name of the current user that sent this request

  • isAdminUser (boolean): Whether the current user is an administrator

  • database (string): The name of the database this request was executed on

  • url (string): The raw request URL

  • protocol (string): The transport protocol, one of "http", "https", "velocystream"

  • portType (string): The type of the socket, one of "tcp/ip", "unix", "unknown"

  • server (object): Attributes of the server connection

    • address (string): The bind address of the endpoint this request was sent to

    • port (integer): The port this request was sent to

    • endpoint (string): The endpoint this request was sent to

  • client (object): Attributes of the client connection

    • address (integer): The IP address of the client

    • port (integer): The port of the TCP connection on the client-side

    • id (string): A server generated ID

  • internals (object): Contents of the server internals struct

  • prefix (object): The prefix of the database

  • headers (object): The list of the HTTP headers you sent

  • requestType (string): The HTTP method that was used for the request ("POST"). The endpoint can be queried using other verbs, too ("GET", "PUT", "PATCH", "DELETE").

  • requestBody (string): Stringified version of the request body you sent

  • rawRequestBody (object): The sent payload as a JSON-encoded Buffer object

  • parameters (object): An object containing the query parameters

  • cookies (object): A list of the cookies you sent

  • suffix (array): A list of the decoded URL path suffixes. You can query the endpoint with arbitrary suffixes, e.g. /_admin/echo/foo/123

  • rawSuffix (array): A list of the percent-encoded URL path suffixes

  • path (string): The relative path of this request (decoded, excluding /_admin/echo)

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.

Responses

HTTP 200: Is returned in all cases.

Initiate shutdown sequence

initiates the shutdown sequence

DELETE /_admin/shutdown

Query Parameters

  • soft (boolean, optional): Introduced in: v3.7.12, v3.8.1, v3.9.0

    If set to true, this initiates a soft shutdown. This is only available on Coordinators. When issued, the Coordinator tracks a number of ongoing operations, waits until all have finished, and then shuts itself down normally. It will still accept new operations.

    This feature can be used to make restart operations of Coordinators less intrusive for clients. It is designed for setups with a load balancer in front of Coordinators. Remove the designated Coordinator from the load balancer before issuing the soft-shutdown. The remaining Coordinators will internally forward requests that need to be handled by the designated Coordinator. All other requests will be handled by the remaining Coordinators, reducing the designated Coordinator’s load.

    The following types of operations are tracked:

    • AQL cursors (in particular streaming cursors)
    • Transactions (in particular stream transactions)
    • Pregel runs (conducted by this Coordinator)
    • Ongoing asynchronous requests (using the x-arango-async: store HTTP header
    • Finished asynchronous requests, whose result has not yet been collected
    • Queued low priority requests (most normal requests)
    • Ongoing low priority requests

This call initiates a clean shutdown sequence. Requires administrative privileges.

Responses

HTTP 200: is returned in all cases, OK will be returned in the result buffer on success.

Query progress of soft shutdown process

query progress of soft shutdown process

GET /_admin/shutdown

Introduced in: v3.7.12, v3.8.1, v3.9.0

This call reports progress about a soft Coordinator shutdown (see documentation of DELETE /_admin/shutdown?soft=true). In this case, the following types of operations are tracked:

  • AQL cursors (in particular streaming cursors)
  • Transactions (in particular stream transactions)
  • Pregel runs (conducted by this Coordinator)
  • Ongoing asynchronous requests (using the x-arango-async: store HTTP header
  • Finished asynchronous requests, whose result has not yet been collected
  • Queued low priority requests (most normal requests)
  • Ongoing low priority requests

This API is only available on Coordinators.

Responses

HTTP 200: The response indicates the fact that a soft shutdown is ongoing and the number of active operations of the various types. Once all numbers have gone to 0, the flag allClear is set and the Coordinator shuts down automatically.

  • softShutdownOngoing (boolean): Whether a soft shutdown of the Coordinator is in progress.

  • AQLcursors (number): Number of AQL cursors that are still active.

  • transactions (number): Number of ongoing transactions.

  • pendingJobs (number): Number of ongoing asynchronous requests.

  • doneJobs (number): Number of finished asynchronous requests, whose result has not yet been collected.

  • pregelConductors (number): Number of ongoing Pregel jobs.

  • lowPrioOngoingRequests (number): Number of queued low priority requests.

  • lowPrioQueuedRequests (number): Number of ongoing low priority requests.

  • allClear (boolean): Whether all active operations finished.

Execute program

Execute a script on the server.

POST /_admin/execute

Request Body

(string, 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.

Responses

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

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

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

Responses

HTTP 200: Status information was returned successfully.

❮  Agency

© ArangoDB - the native multi-model NoSQL database