v8 v7 v6 v5 v4 v3
Edit Page

Databases and Collections

🔧 Configuration

Sets localhost:8080 with admin:secret
Values are saved in your browser

RESTHeart allows managing dbs and collections.

Create a collection

cURL

curl -X PUT [INSTANCE-URL]/foo \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -H "Content-Type: application/json" \
  -d '{ "descr": "just a test collection" }'

HTTPie

echo '{ "descr": "just a test collection" }' | http PUT [INSTANCE-URL]/foo \
  Authorization:"Basic [BASIC-AUTH]"

JavaScript

fetch('[INSTANCE-URL]/foo', {
  method: 'PUT',
  body: JSON.stringify({ "descr": "just a test collection" }),
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  if (response.ok) {
    console.log('Collection created successfully');
  } else {
    console.error('Failed to create collection:', response.status);
  }
})
.catch(error => console.error('Error:', error));
HTTP/1.1 201 Created

Note that RESTHeart allows to set properties for collections.

Note

Note that some properties are metadata, i.e. they have a special meaning for RESTheart that influences its behavior.

The collection’s properties can be read as follows:

cURL

curl -X GET [INSTANCE-URL]/foo/_meta \
  -H "Authorization: Basic [BASIC-AUTH]"

HTTPie

http GET [INSTANCE-URL]/foo/_meta \
  Authorization:"Basic [BASIC-AUTH]"

JavaScript

fetch('[INSTANCE-URL]/foo/_meta', {
  method: 'GET',
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved collection metadata:', data);
})
.catch(error => console.error('Error:', error));
HTTP/1.1 200 OK

{
    "_etag": {
        "$oid": "5d95ef77ab3cf85b199ed3b7"
    },
    "_id": "_meta",
    "descr": "just a test collection"
}

Modify the properties of a collection

PUT and PATCH verbs modify the properties of the collection.

Note

PATCH modifies only properties in the request body; PUT replaces the whole properties set.

cURL

curl -X PATCH [INSTANCE-URL]/foo \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -H "Content-Type: application/json" \
  -d '{ "owner": "Bob" }'

HTTPie

echo '{ "owner": "Bob" }' | http PATCH [INSTANCE-URL]/foo \
  Authorization:"Basic [BASIC-AUTH]"

JavaScript

fetch('[INSTANCE-URL]/foo', {
  method: 'PATCH',
  body: JSON.stringify({ "owner": "Bob" }),
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  if (response.ok) {
    console.log('Collection properties updated successfully');
  } else {
    console.error('Failed to update collection properties:', response.status);
  }
})
.catch(error => console.error('Error:', error));
HTTP/1.1 200 OK

Delete a collection

To delete a collection, the ETag must be passed using the If-Match request header.

Let’s try to delete the collection foo without passing it.

cURL

curl -X DELETE [INSTANCE-URL]/foo \
  -H "Authorization: Basic [BASIC-AUTH]"

HTTPie

http DELETE [INSTANCE-URL]/foo \
  Authorization:"Basic [BASIC-AUTH]"

JavaScript

fetch('[INSTANCE-URL]/foo', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => {
  if (response.ok) {
    console.log('Collection deletion request executed successfully');
  } else {
    console.error('Collection deletion request failed:', response.status);
  }
})
.catch(error => console.error('Error:', error));
HTTP/1.1 409 Conflict
...
ETag: 5d95ef77ab3cf85b199ed3b7

{
    "http status code": 409,
    "http status description": "Conflict",
    "message": "The ETag must be provided using the 'If-Match' header."
}

Now let’s pass the If-Match` request header, the collection will be deleted.

cURL

curl -X DELETE [INSTANCE-URL]/foo \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -H "If-Match: 5d95ef77ab3cf85b199ed3b7"

HTTPie

http DELETE [INSTANCE-URL]/foo \
  Authorization:"Basic [BASIC-AUTH]" \
  If-Match:5d95ef77ab3cf85b199ed3b7

JavaScript

fetch('[INSTANCE-URL]/foo', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]',
    'If-Match': '5d95ef77ab3cf85b199ed3b7'
  }
})
.then(response => {
  if (response.ok) {
    console.log('Collection deleted successfully');
  } else {
    console.error('Failed to delete collection:', response.status);
  }
})
.catch(error => console.error('Error:', error));
HTTP/1.1 204 No Content

Before running the example requests for dbs

The following examples that all dbs are exposes via RESTHeart. For this, edit the property file etc/default.properties and set root-mongo-resource = '*':

# The MongoDB resource to bind to the root URI /
# The format is /db[/coll[/docid]] or '*' to expose all dbs
root-mongo-resource = '*'

After restarting RESTHeart, all MongoDB resources are exposes by RESTHeart. With this configuration the URIs are a follows:

  • database: /restheart,

  • collection: /restheart/inventory

  • document: /restheart/inventory/5d08b08097c4c04680c41579.

For instance, we can list the existing dbs as follows:

cURL

curl -X GET [INSTANCE-URL]/ \
  -H "Authorization: Basic [BASIC-AUTH]"

HTTPie

http GET [INSTANCE-URL]/ \
  Authorization:"Basic [BASIC-AUTH]"

JavaScript

fetch('[INSTANCE-URL]/', {
  method: 'GET',
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved databases:', data);
})
.catch(error => console.error('Error:', error));
[
    "restheart",
    "myDb",
    ...
]

Create a db

cURL

curl -X PUT [INSTANCE-URL]/newDb \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -H "Content-Type: application/json" \
  -d '{ "descr": "just a test db" }'

HTTPie

echo '{ "descr": "just a test db" }' | http PUT [INSTANCE-URL]/newDb \
  Authorization:"Basic [BASIC-AUTH]"

JavaScript

fetch('[INSTANCE-URL]/newDb', {
  method: 'PUT',
  body: JSON.stringify({ "descr": "just a test db" }),
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  if (response.ok) {
    console.log('Database created successfully');
  } else {
    console.error('Failed to create database:', response.status);
  }
})
.catch(error => console.error('Error:', error));
HTTP/1.1 201 Created

Note that RESTHeart allows to set properties for dbs.

Note

Note that some properties are metadata, i.e. they have a special meaning for RESTheart that influences its behavior.

This properties can be read as follows:

cURL

curl -X GET [INSTANCE-URL]/newDb/_meta \
  -H "Authorization: Basic [BASIC-AUTH]"

HTTPie

http GET [INSTANCE-URL]/newDb/_meta \
  Authorization:"Basic [BASIC-AUTH]"

JavaScript

fetch('[INSTANCE-URL]/newDb/_meta', {
  method: 'GET',
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Retrieved database metadata:', data);
})
.catch(error => console.error('Error:', error));
HTTP/1.1 200 OK

{
    "_etag": {
        "$oid": "5d95ed1dab3cf85b199ed3b6"
    },
    "_id": "_meta",
    "desc": "just a test db"
}

Modify the properties of a db

PUT and PATCH verbs modify the properties of the database.

cURL

curl -X PATCH [INSTANCE-URL]/newDb \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -H "Content-Type: application/json" \
  -d '{ "owner": "Bob" }'

HTTPie

echo '{ "owner": "Bob" }' | http PATCH [INSTANCE-URL]/newDb \
  Authorization:"Basic [BASIC-AUTH]"

JavaScript

fetch('[INSTANCE-URL]/newDb', {
  method: 'PATCH',
  body: JSON.stringify({ "owner": "Bob" }),
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  if (response.ok) {
    console.log('Database properties updated successfully');
  } else {
    console.error('Failed to update database properties:', response.status);
  }
})
.catch(error => console.error('Error:', error));
HTTP/1.1 200 OK

Delete a db

To delete a db, the ETag must be passed using the If-Match request header.

Let’s try to delete the newDb without passing it.

cURL

curl -X DELETE [INSTANCE-URL]/newDb \
  -H "Authorization: Basic [BASIC-AUTH]"

HTTPie

http DELETE [INSTANCE-URL]/newDb \
  Authorization:"Basic [BASIC-AUTH]"

JavaScript

fetch('[INSTANCE-URL]/newDb', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]'
  }
})
.then(response => {
  if (response.ok) {
    console.log('Database deletion request executed successfully');
  } else {
    console.error('Database deletion request failed:', response.status);
  }
})
.catch(error => console.error('Error:', error));
HTTP/1.1 409 Conflict
...
ETag: 5d95ed1dab3cf85b199ed3b6

{
    "http status code": 409,
    "http status description": "Conflict",
    "message": "The database's ETag must be provided using the 'If-Match' header."
}

Now let’s pass the If-Match` request header, the db will be deleted.

cURL

curl -X DELETE [INSTANCE-URL]/newDb \
  -H "Authorization: Basic [BASIC-AUTH]" \
  -H "If-Match: 5d95ed1dab3cf85b199ed3b6"

HTTPie

http DELETE [INSTANCE-URL]/newDb \
  Authorization:"Basic [BASIC-AUTH]" \
  If-Match:5d95ed1dab3cf85b199ed3b6

JavaScript

fetch('[INSTANCE-URL]/newDb', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Basic [BASIC-AUTH]',
    'If-Match': '5d95ed1dab3cf85b199ed3b6'
  }
})
.then(response => {
  if (response.ok) {
    console.log('Database deleted successfully');
  } else {
    console.error('Failed to delete database:', response.status);
  }
})
.catch(error => console.error('Error:', error));
HTTP/1.1 204 No Content