Building a Simple Spring Boot API with ArangoDB on ECS

By Dassi Orleando, Alibaba Cloud Tech Share Author. Tech Share is Alibaba Cloud’s incentive program to encourage the sharing of technical knowledge and best practices within the cloud community.


ArangoDB is a multi-model NoSQL database management system allowing to build high performance applications using a convenient SQL-like query language or JavaScript extensions.

Previously, we’ve seen how to install ArangoDB (server and client) into an Alibaba Cloud Elastic Compute Service (ECS) Ubuntu instance and experimented with the command-line and graphical tools to perform some operations on databases, collections and users. Let’s consider we’ve that base to better follow the current write-up which will show a basic API building using ArangoDB as database engine into a Spring-Boot based project.


  1. Basic Java/Spring understanding
  2. Installed ArangoDB server on Alibaba Cloud ECS
  3. Read the article “ArangoDB on Alibaba Cloud ECS”

Setting up a Spring-Boot Project

We’ll be building a simple API using Java/Spring resources. Here are some important dependencies

  • ArangoDB Java driver, the official ArangoDB Java driver
  • arangodb-spring-data is the Spring Data wrapper used to easy database operations

Maven will be used as build automation to configure our project and setup the dependencies.

Initiating the Project

Let’s visit to generate the structure of a Spring Boot project with the Web dependency as shown below:

Now we’ve a fresh Maven project we can unzip and open with our favorite Java IDE.


Spring Data ArangoDB requires at least ArangoDB 3.0 to function.

Note: ArangoDB Java driver can be used in any Java application while arango-db-spring-data is proper for those Spring projects where we want to use repositories.

Let’s be sure the pom.xml have almost the following structure and/or content:

Create Database & Collection

ArangoDB’s multi-model feature allows to manage many types of database with the same engine, for the sake of this article we will create and use a Document database for a basic CRUD API.

From the dashboard let’s create a database called alibabacloudblog as illustrated in the screenshot below (owned by the current user: root):

Let’s switch to be connected to the database we have just created (still from the admin panel) so that we’ll manage our database to do things like create collections (represents table in relational DBMS).

We then create the article collection, it’s a self-explaining word representing an article as in a blog with title and content as main fields.

As example, here’s the screen to create the Document collection article:

Database Configuration

Let’s create our custom database configuration class ArangoDBConfiguration, it’s where we’ll define our database user credentials to use within the project, the database name as well as the ArangoDB host.

The configuration class is as follow:

Another option which is the most used as it’s easy to identify in a large project is to use a configuration file located in the resources folder of our project, here’s how our file content should be:

Here’s how to load this file so that our bean will be configured as stated:

Note: When using ArangoDB 3.0 it is required to set the transport protocol to HTTP and fetch the dependency org.apache.httpcomponents:httpclient, here’s the maven syntax to use:

Article Model

Let’s show how simple it’s to define a model in the following case, here’s the content:

Article Service

Next, we create the Article service. It’s actually the place we’ll be writing every codes necessary to manage Article while interacting with the correct database collection.

Spring Data provides default implementations for most CRUD operations which Spring Data ArangoDB is built on (we first inject the article repository):

This service is used as an interface for operations across Article collections and/or further custom business logics, these functions will then be used into the Article controller.

Note that all documents created in any collections will automatically get the following server-generated attributes:

  • _id: A unique id, consisting of collection name and a server-side sequence value
  • _key: The server sequence value
  • _rev: The document’s revision id

Whenever you run queries on the documents in collections, don’t be surprised if these additional attributes are returned as well.

At any moment of your App development you can decide to add more fields to a collection’s document by just updating the Article model (an annotated POJO), as the field are dynamic there is no need to perform any other special queries on other documents unless you’ve something else to accomplish.

You can count the number of documents of a collections using the following query as described in the guide:

A more populated approach to handle the whole data would have been by making a JOIN between two collections, one the Article who serve to define the blog’s article model and another the user defining the article’s authors. Let’s read more about join here.

Instead of using the predefined collections functions we have up here in the ArangoDB Spring Data, one might try writing plain AQL queries and end up with the same results, here’s a simple query getting a user by its Name and ID (using bind parameters):


Here are some keywords available to use in order to perform AQL queries:

  • FOR: array iteration
  • RETURN: results projection
  • FILTER: results filtering
  • SORT: result sorting
  • LIMIT: result slicing
  • LET: variable assignment
  • COLLECT: result grouping
  • INSERT: insertion of new documents
  • UPDATE: (partial) update of existing documents
  • REPLACE: replacement of existing documents
  • REMOVE: removal of existing documents
  • UPSERT: insertion or update of existing documents

When it comes to more complex queries queries using ArangoDB Query Language (AQL) can be supplied with the @Query annotation on methods in our repositories and we call the corresponding function as other.

Query example into a repository:

Instead, we can only define the following repository method to perform the same query, but now with Spring Data possibilities:

Here’s the ArticleRepository content:

If interested in using it for custom business logic into your API, here is the AQL getting started which is clearly showing details on how to use AQL. Queries guide with more examples are available on the reference manual.

Article Controller

The article controller is following Spring MVC in a rest way, so that it’s just dealing with incoming parameter while sending back JSON data as output:

Run the API

A simple command is available to run our API on our ECS or locally on any computer as simply as typing mvn spring-boot:run knowing that you’ve compiled (mvn clean install) your project before.

When running ArangoDB, you may encounter some issues as discussed in the following link:


In this article, we’ve seen how to build a basic Spring Boot API using ArangoDB as the database management system with its ArangoDB Java Driver wrapped by Spring Data ArangoDB interface.

The full source code for this article can be found on my GitHub page.


Follow me to keep abreast with the latest technology news, industry insights, and developer trends.

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