HTTP interface for databases

The HTTP API for databases lets you create and delete databases, list available databases, and get information about specific databases

The HTTP interface for databases provides operations to create and drop individual databases. These are mapped to the standard POST and DELETE HTTP methods. There is also the GET method to retrieve an array of existing databases.

All database management operations can only be accessed via the default _system database and none of the other databases.

Addresses of databases

Any operation triggered via ArangoDB’s RESTful HTTP API is executed in the context of exactly one database. To explicitly specify the database in a request, the request URI must contain the database name before the actual path:

http://localhost:8529/_db/mydb/...

The ... placeholder is the actual path to the accessed resource. In the example, the resource is accessed in the context of the mydb database. Actual URLs in the context of mydb could look like this:

http://localhost:8529/_db/mydb/_api/version
http://localhost:8529/_db/mydb/_api/document/test/12345
http://localhost:8529/_db/mydb/myapp/get

Special characters in database names must be properly URL-encoded, e.g. a + b = c needs to be encoded as a%20%2B%20b%20%3D%20c:

http://localhost:8529/_db/a%20%2B%20b%20%3D%20c/_api/version

Database names containing Unicode must be properly NFC-normalized. Non-NFC-normalized names are rejected by the server.

Manage databases

Information of the database

retrieves information about the current database

GET /_api/database/current

Retrieves the properties of the current database

The response is a JSON object with the following attributes:

name: the name of the current database
id: the id of the current database
path: the filesystem path of the current database
isSystem: whether or not the current database is the _system database
sharding: the default sharding method for collections created in this database
replicationFactor: the default replication factor for collections in this database
writeConcern: the default write concern for collections in this database

Responses

HTTP 200: is returned if the information was retrieved successfully.

HTTP 400: is returned if the request is invalid.

HTTP 404: is returned if the database could not be found.

Examples

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

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 93
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "result" : { 
    "id" : "1", 
    "name" : "_system", 
    "isSystem" : true, 
    "path" : "none" 
  } 
}

Hide response body

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

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 93
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Show response body

List of accessible databases

retrieves a list of all databases the current user can access

GET /_api/database/user

Retrieves the list of all databases the current user can access without specifying a different username or password.

Responses

HTTP 200: is returned if the list of database was compiled successfully.

HTTP 400: is returned if the request is invalid.

Examples

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

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 47
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "result" : [ 
    "_system" 
  ] 
}

Hide response body

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

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 47
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Show response body

List of databases

retrieves a list of all existing databases

GET /_api/database

Retrieves the list of all existing databases

Note: retrieving the list of databases is only possible from within the _system database.

Note: You should use the GET user API to fetch the list of the available databases now.

Responses

HTTP 200: is returned if the list of database was compiled successfully.

HTTP 400: is returned if the request is invalid.

HTTP 403: is returned if the request was not executed in the _system database.

Examples

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

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 47
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "result" : [ 
    "_system" 
  ] 
}

Hide response body

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

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 47
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Show response body

Create database

creates a new database

POST /_api/database

Request Body

name (string, required): Has to contain a valid database name. The name must conform to the selected naming convention for databases. If the name contains Unicode characters, the name must be NFC-normalized. Non-normalized names will be rejected by arangod.
options (object, optional): Optional object which can contain the following attributes:
- sharding (string, optional): The sharding method to use for new collections in this database. Valid values are: “”, “flexible”, or “single”. The first two are equivalent. (cluster only)
- replicationFactor (integer, optional): Default replication factor for new collections created in this database. Special values include “satellite”, which will replicate the collection to every DB-Server (Enterprise Edition only), and 1, which disables replication. (cluster only)
- writeConcern (number, optional): Default write concern for new collections created in this database. It determines how many copies of each shard are required to be in sync on the different DB-Servers. If there are less than these many copies in the cluster, a shard refuses to write. Writes to shards with enough up-to-date copies succeed at the same time, however. The value of writeConcern cannot be larger than replicationFactor. For SatelliteCollections, the writeConcern is automatically controlled to equal the number of DB-Servers and has a value of 0. (cluster only)
users (array, optional): An array of user objects. The users will be granted Administrate permissions for the new database. Users that do not exist yet will be created. If users is not specified or does not contain any users, the default user root will be used to ensure that the new database will be accessible after it is created. The root user is created with an empty password should it not exist. Each user object can contain the following attributes:
- username (string, required): Login name of an existing user or one to be created.
- passwd (string, optional): The user password as a string. If not specified, it will default to an empty string. The attribute is ignored for users that already exist.
- active (boolean, optional): A flag indicating whether the user account should be activated or not. The default value is true. If set to false, then the user won’t be able to log into the database. The default is true. The attribute is ignored for users that already exist.
- extra (object, optional): A JSON object with extra user information. It is used by the web interface to store graph viewer settings and saved queries. Should not be set or modified by end users, as custom attributes will not be preserved.

Creates a new database

The response is a JSON object with the attribute result set to true.

Note: creating a new database is only possible from within the _system database.

Responses

HTTP 201: is returned if the database was created successfully.

HTTP 400: is returned if the request parameters are invalid or if a database with the specified name already exists.

HTTP 403: is returned if the request was not executed in the _system database.

HTTP 409: is returned if a database with the specified name already exists.

Examples

Creating a database named example.

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/database <<EOF
{ 
  "name" : "example", 
  "options" : { 
    "sharding" : "flexible", 
    "replicationFactor" : 3 
  } 
}
EOF

HTTP/1.1 201 Created
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 40
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 201, 
  "result" : true 
}

Hide response body

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/database <<EOF
{ 
  "name" : "example", 
  "options" : { 
    "sharding" : "flexible", 
    "replicationFactor" : 3 
  } 
}
EOF

HTTP/1.1 201 Created
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 40
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Show response body

Creating a database named mydb with two users, flexible sharding and default replication factor of 3 for collections that will be part of the newly created database.

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/database <<EOF
{ 
  "name" : "mydb", 
  "users" : [ 
    { 
      "username" : "admin", 
      "passwd" : "secret", 
      "active" : true 
    }, 
    { 
      "username" : "tester", 
      "passwd" : "test001", 
      "active" : false 
    } 
  ] 
}
EOF

HTTP/1.1 201 Created
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 40
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 201, 
  "result" : true 
}

Hide response body

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/database <<EOF
{ 
  "name" : "mydb", 
  "users" : [ 
    { 
      "username" : "admin", 
      "passwd" : "secret", 
      "active" : true 
    }, 
    { 
      "username" : "tester", 
      "passwd" : "test001", 
      "active" : false 
    } 
  ] 
}
EOF

HTTP/1.1 201 Created
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 40
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Show response body

Drop database

drop an existing database

DELETE /_api/database/{database-name}

Path Parameters

database-name (string, required): The name of the database

Drops the database along with all data stored in it.

Note: dropping a database is only possible from within the _system database. The _system database itself cannot be dropped.

Responses

HTTP 200: is returned if the database was dropped successfully.

HTTP 400: is returned if the request is malformed.

HTTP 403: is returned if the request was not executed in the _system database.

HTTP 404: is returned if the database could not be found.

Examples

shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/database/example

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 40
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "result" : true 
}

Hide response body

shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/database/example

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 40
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Show response body

❮ Users Collections ❯