RESTHeart is the REST API server for MongoDB. It embeds the Undertow high performance, non-blocking HTTP server. It is entirely written in Java and distributed as open source software under the GNU AGPL v3.0.
RESTHeart was born as an API server for MongoDB, but AWS DocumentDB is compatible with MongoDB and this makes RESTHeart an effective tool for the creation of Web APIs on top of the new Amazon’s As-a-Service database.
Amazon DocumentDB (with MongoDB compatibility) is a fast, scalable, highly available, and fully managed document database service that supports MongoDB workloads.
The fairly common scenario that we intend to demonstrate here is the following: we want our DocumentDB database to be accessible from external clients via APIs that will be invoked through simple HTTP calls.
To achieve this we will need a relatively simple architecture that includes the following components:
- A cluster for our DocumentDB instance.
- An EC2 instance running RESTHeart.
Creating the DocumentDB’s cluster
From the AWS Dashboard go to the section dedicated to DocumentDB and click on ‘Create’ a new cluster.
Warning: the smallest available instance for DocumentDB is ‘db.r4.large’ which could be pretty expensive in the long term: select ‘1’ as the ‘Number of instances’ instead of ‘3’ and don’t forget to destroy both the cluster AND the instance when finished with this demo!
Complete the creation by specifying a name, class, and number of instances of our cluster. Finally, create credentials for the cluster’s administrator user.
At the end of the creation process, the newly created cluster is available on the dashboard.
The last step is to modify the VPC’s Security Group, in order to open the port 27017, to give database access to RESTHeart.
The cluster configuration is now complete! Let’s see how to configure RESTHeart.
You can delete at any time your DocuemntDb instance and cluster by selecting them from the dashboard and clicking on Delete (read here for more details).
At this point is necessary to create an EC2 instance to run RESTHeart and configure it to call our DocumentDB database.
This step is mandatory because, by default, DocumentDB instances are created within a private VPC, which is not directly accessible from the public Internet. This EC2 server could then be used as a “bastion host” which allows connecting to the database also from the mongo shell — something which is impossibile directly from your laptop.
Go to the section dedicated to “EC2 instances” from the AWS dashboard and click on ‘Launch instance’. For example, choose a T2.micro EC2 image with Ubuntu 18.04 TLS. Despite being small, it’s enough to run RESTHeart.
Leave all the default settings, paying attention to choose the same VPC in which you have created the DocumentDB cluster and a Security Group that has opened both ports 22 (for SSH connections) and 8080 (from where RESTHeart will publish its REST API).
Once initialized we will be able to connect using the .pem calls that we have chosen during the creation phase.
$ ssh ubutu@<ec2-public-ip>
Now that we are connected to our EC2 instance we want to try to connect to our DocumentDB database.
Install the mongo-client package
$ sudo apt install mongodb-clients
Then install Java
$ sudo apt-get install default-jdk
By default, a newly created Amazon DocumentDB cluster only accepts secure connections using Transport Layer Security (TLS) (see the documentation).
Before you can connect using TLS, you first need to download the public key for Amazon DocumentDB. You can download the public key using the following command:
When you visit this URL, you download a file named
rds-combined-ca-bundle.pem. When you connect to your Amazon DocumentDB cluster via SSL, specify the
.pem file public key, as shown in this example:
$ mongo --ssl --host endpoint –-sslCAFile rds-combined-ca-bundle.pem --username yourMasterUsername --password yourMasterPassword
The connection was successful, now we can install RESTHeart and configure it to point to DocumentDB.
First create the keystore via keytool, importing the pem public certificate just downloaded and necessary to connect securely to DocumentDB from Java applications (keytool is the standard JDK tool to manage local keystores for cryptographic keys).
$ keytool -importcert -file rds-combined-ca-bundle.pem -alias mongoCert -keystore rhTrustStore# asks for password, use "changeit"
Then download the latest release of RESTHeart, untar and cd into it.
$ wget https://github.com/SoftInstigate/restheart/releases/download/3.10.0/restheart-3.10.0.tar.gz$ tar -zxf restheart-3.10.0.tar.gz$ cd restheart-3.10.0/$ ls -l
-rw-r--r-- 1 34519 Apr 27 16:01 LICENSE.txt
-rw-r--r-- 1 4995 Apr 27 16:01 README.md
drwxr-xr-x 4 128 May 14 11:41 etc
-rw-r--r-- 1 16825773 Apr 27 16:02 original-restheart.jar
-rw-r--r-- 1 16825773 Apr 27 16:03 restheart.jar
Let’s configure the MONGO_URI environment variable, pointing it to the DocumentDB instance.
$ export MONGO_URI=’mongodb://restheart:restheart00@docdb-restheart-2019–05–06.cluster-ccexczqns5xm.eu-west-1.docdb.amazonaws.com:27017/ssl=true'
Note: for a complete overview of RESTHeart’s configuration options have a look at its official documentation.
Finally, launch the restheart.jar self-executable over TLS/SSL (see the official documentation).
$ java -server -Dfile.encoding=UTF-8 -Djavax.net.ssl.trustStore=rhTrustStore -Djavax.net.ssl.trustStorePassword=changeit -Djavax.security.auth.useSubjectCredsOnly=false -jar restheart.jar
If RESTHeart can connect to MongoDB then its log will show the exact version, e.g. “Mongo version 3.6.0” and the final message “RESTHeart started”. RESTHeart detects if MongoDB is in Replica Set or not. Below is an example output.
If RESTHeart is running properly configured, notice a WARN message at the very beginning that informs us that the default mongo-uri (which usually points to localhost:27017) has been overridden with the MONGO_URI environment variable we just set, so that it now points to the remote DocumentDB instance:
>>> Found environment variable MONGO_URI overriding parameter mongo-uri
The other warning messages inform us that RESTHeart is configured without an Identity Manager and no Access Manager, therefore the authentication takes place through the default configuration. To enable request authentication and authorization please refer to the documentation available here.
The REST API is ready and we can test the calls to the DocumentDB database from a laptop.
You can use curl.
$ curl -i --user admin:changeit -X GET <ec2-public-ip>:8080/
Or you can use httpie.
$ http -a admin:changeit GET <ec2-public-ip>:8080/
Note that the <ec2-public-ip> below refers to the Ubuntu host where we have just installed RESTHeart, not the EC2 instance part of the DocumentDB cluster!
Our database is accessible from the Internet with simple HTTP calls.
We can use all the features of RESTHeart to perform all the CRUD operations on the database, and much more.
You might want to play with RESTHeart following the tutorial available here.
The compatibility of DocumentDB with MongoDB makes RESTHeart an extremely effective tool for creating a RESTful API on top of the Amazon database. So as we would configure RESTHeart to point to a MongoDB database, we can configure it to access a DocumentDB database.
The configuration versatility of RESTHeart combined with a managed database like DocumentDB makes the creation of cloud backend environments simple and fast, without having to write a single line of code.