How to create a Web API for AWS DocumentDB (using RESTHeart)

RESTHeart is the Open Source Instant API server for your Data. It leverages MongoDB and provides the API to build modern applications. With RESTHeart your get the 80% common requirements out-of-the-box while you can easily extend it for the 20%.

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:

1. A cluster for our DocumentDB instance.
2. 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.r5.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 RESTHeart access to the database access.

The cluster configuration is now complete! Let’s see how to configure RESTHeart.

You can delete at any time your DocumentDb instance and cluster by selecting them from the dashboard and clicking on Delete (read here for more details).

RESTHeart’s configuration

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.

Read Connecting to an Amazon DocumentDB Cluster from Outside an Amazon VPC for more.

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 ubuntu@<ec2-public-ip>

Now that we are connected to our EC2 instance we want to try to connect to our DocumentDB database.

Install the official mongodb-org package. In this scenario we will install the community edition for Ubuntu 18.04 OS. (see the documentation)

Import MongoDB public GPG Key

$ wget -qO - https://www.mongodb.org/static/pgp/server-4.4.asc | sudo apt-key add -

Create the /etc/apt/sources.list.d/mongodb-org-4.4.list file

$ echo “deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu bionic/mongodb-org/4.4 multiverse” | sudo tee /etc/apt/sources.list.d/mongodb-org-4.4.list

Reload local package database

$ sudo apt update

Install latest mongodb-org packages

$ sudo apt install -y mongodb-org

Then install Java

$ sudo apt 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:

$ wget https://s3.amazonaws.com/rds-downloads/rds-ca-2019-root.pem

When you visit this URL, you download a file namedrds-ca-2019-root.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-ca-2019-root.pem 
--username yourMasterUsername --password yourMasterPassword

The connection was successful, now we can install RESTHeart and configure it to point to DocumentDB.

Download RESTHeart (you will receive an email with a trial license key) and run the setup as indicated in the official documentation.

After having installed RESTHeart, you 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-ca-2019-root.pem -alias mongoCert -keystore rhTrustStore
# asks for password, use "changeit"

Then download the latest release of RESTHeart, untar and move into it:

$ wget https://github.com/SoftInstigate/restheart/releases/download/5.1.5/
restheart.tar.gz
$ tar -zxf restheart.tar.gz
$ cd restheart/
$ mv ../rhTrustStore ./
$ ls -l
total 18460 
-rw-r--r-- 1 ubuntu ubuntu    34519 Aug 20 13:53 LICENSE.txt 
-rw-r--r-- 1 ubuntu ubuntu      322 Aug 20 13:53 README.md 
drwxrwxr-x 2 ubuntu ubuntu     4096 Aug 31 11:13 etc 
-rw------- 1 ubuntu ubuntu   196580 Sep  3 08:05 nohup.out 
drwxrwxr-x 2 ubuntu ubuntu     4096 Aug 31 10:33 plugins 
-rw-rw-r-- 1 ubuntu ubuntu     1456 Sep  4  2019 rds-ca-2019-root.pem 
-rw-r--r-- 1 ubuntu ubuntu 18643700 Aug 20 13:53 restheart.jar 
-rw-rw-r-- 1 ubuntu ubuntu     1338 Aug 31 11:20 rhTrustStore

Duplicate the default configuration file:

$ cp ./etc/default.properties ./etc/documentdb.properties

Open the newly createddocumentdb.propertieswith an editor of your choice, find the key mongo-uri and set your mongo connection string as shown below.

mongo-uri = mongodb://<username>:<psw>@<enpoint>/?ssl=true&retryWrites=false

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 etc/restheart.yml -e etc/documentdb.properties

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.

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:secret -X GET <ec2-public-ip>:8080/

Or you can use httpie.

$ http -a admin:secret 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!

Done!

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.

Conclusions

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.