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. The database name is read from the first part
of the request URI path (e.g. /_db/mydb/...). If the request URI does not
contain a database name, it defaults to /_db/_system.
To explicitly specify the database in a request, the request URI must contain
the database name at the beginning of the 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
Database management operations like listing, creating, and dropping databases
can only be executed with the _system database as the context.
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
GET
/_db/{database-name}/_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 databaseid: the id of the current databasepath: the filesystem path of the current databaseisSystem: whether or not the current database is the _system databasesharding: the default sharding method for collections created in this databasereplicationFactor: the default replication factor for collections in this databasewriteConcern: the default write concern for collections in this database
Path Parameters
database-name*
string
The name of the database.
Responses
200
OK
is returned if the information was retrieved successfully.
400
Bad Request
is returned if the request is invalid.
404
Not Found
is returned if the database could not be found.
Examples
curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/database/current'
Show outputHTTP/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"
}
}
List the accessible databases
GET
/_db/{database-name}/_api/database/user
Retrieves the list of all databases the current user can access without
specifying a different username or password.
Path Parameters
database-name*
string
The name of a database. Which database you use doesn’t matter as long
as the user account you authenticate with has at least read access
to this database.
Responses
200
OK
is returned if the list of database was compiled successfully.
400
Bad Request
is returned if the request is invalid.
Examples
curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/database/user'
Show outputHTTP/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"
]
}
List all databases
GET
/_db/_system/_api/database
Retrieves the list of all existing databases
Retrieving the list of databases is only possible from within the _system database.
Responses
200
OK
is returned if the list of database was compiled successfully.
400
Bad Request
is returned if the request is invalid.
403
Forbidden
is returned if the request was not executed in the _system database.
Examples
curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/database'
Show outputHTTP/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"
]
}
Create a database
POST
/_db/_system/_api/database
Creates a new database.
The response is a JSON object with the attribute result set to true.
Creating a new database is only possible from within the _system database.
Request Body application/json object
name*
string
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 object which can contain the following attributes:
replicationFactor
integer
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)
sharding
string
The sharding method to use for new collections in this database. Valid values
are: “”, “flexible”, or “single”. The first two are equivalent. (cluster only)
writeConcern
number
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 greater than replicationFactor.
If distributeShardsLike is set, the writeConcern
is that of the prototype collection.
For SatelliteCollections, the writeConcern is automatically controlled to
equal the number of DB-Servers and has a value of 0.
Otherwise, the default value is controlled by the --cluster.write-concern
startup option, which defaults to 1. (cluster only)
users
array of objects
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:
active
boolean
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
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.
passwd
string
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.
username*
string
Login name of an existing user or one to be created.
Responses
201
Created
is returned if the database was created successfully.
400
Bad Request
is returned if the request parameters are invalid, if a database with the
specified name already exists, or if the configured limit to the number
of databases has been reached.
403
Forbidden
is returned if the request was not executed in the _system database.
409
Conflict
is returned if a database with the specified name already exists.
Examples
Creating a database named example.
curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/database' <<'EOF'
{
"name": "example",
"options": {
"sharding": "flexible",
"replicationFactor": 3
}
}
EOF
Show outputHTTP/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
}
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.
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
Show outputHTTP/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
}
Drop a database
DELETE
/_db/_system/_api/database/{database-name}
Drops the database along with all data stored in it.
Dropping a database is only possible from within the _system database.
The _system database itself cannot be dropped.
Responses
200
OK
is returned if the database was dropped successfully.
400
Bad Request
is returned if the request is malformed.
403
Forbidden
is returned if the request was not executed in the _system database.
404
Not Found
is returned if the database could not be found.
Examples
curl -X DELETE --header 'accept: application/json' --dump - 'http://localhost:8529/_api/database/example'
Show outputHTTP/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
}
