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

Riccardo Corti
May 16, 2019 · 7 min read
Image for post
Image for post

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

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.

Image for post
Image for post

Image for post
Image for post

At the end of the creation process, the newly created cluster is available on the dashboard.

Image for post
Image for post

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.

Image for post
Image for post

Image for post
Image for post

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

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.

Image for post
Image for post

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).

Image for post
Image for post

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>
Image for post
Image for post

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
Image for post
Image for post

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.

Image for post
Image for post

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!

Image for post
Image for post

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 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.

SoftInstigate Team

Random thoughts about Software Development, Technology…

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store