ArangoDB Foxx

Foxx is a JavaScript framework that allows you to write rich data-centric microservices. It is executed directly inside of ArangoDB and grants you high speed, raw access to your data.
With Foxx you can embed complex queries and data-focused business logic into your database. On top, the Foxx framework can serve you an administration GUI for the service.

Why to add business logic to your database?

First of all it yields performance benefits, the data analysis and modification is executed as close to the data as possible. Also it requires one network hop less as the foxx has direct access to the data and does not have to query a database located on a different server.

Second, your application is completely free of any database related information like queries, it is just requesting an endpoint that gives the data in the expected format. This allows you to reuse this endpoint in different applications:

Third, Foxx adds another level of security to your application, you can manage the access rights on any level you like: application, collection, document or even attribute.

Finally, Foxx is automatically scaled alongside your database: if the number of ArangoDB servers grows, so does your microservice servers.

What are good use cases for ArangoDB Foxx?

  • Reduce duplication: Have a consistent HTTP API for your different services or applications and don’t duplicate logic between them.
  • Reduce the number of requests between database and backend: It is also really useful to reduce the number of requests between the database and your backend. Just put aggregations or logic in Foxx, so you get exactly the data you need from the database – no need to communicate back and forth.
  • Triggers, even using external services: Put your triggers into Foxx apps – even if they need external services. Want to send out an email every time a user is created? No problem. Foxx has background workers that can do this for you.
  • Abstractions over implementation details: It’s also a way to abstract implementation details like the structure of your data, joins and all those things away from your application. Just define clean and easy endpoints that deliver the data exactly as you need it.
  • Execute data intensive operations: Improve the app performance by executing data-intensive operations directly in the database.
  • API for your mobile or single page web applications: Reuse your API easily, e.g. from an Android/iOS app or your single page web application.

Foxx has full access to all features of ArangoDB including the query language AQL, transactions, graph traversals and simple queries. And as Foxx runs inside of ArangoDB that means direct access without any communication overhead.

Foxx as your data-centric microservice framework

In the recent movements of software development many companies of all sizes talk about
moving away from large monolithic applications and switch over to a microservice based software architecture.
Because microservices yield many benefits in terms of scaling and zero-downtime.

During the design of Foxx we followed the concepts and ideas of microservices.
Our baseline is the definition by Martin Fowler and James Lewis given in their microservice article.
The following table lists a mapping of microservice concepts and how they can be realized within Foxx:

microservice Foxx description
Few lines of Code Little Boilerplate Most of the boilerplate is already handled by the Foxx environment. You can focus on your business logic
HTTP API Controller The Foxx controller allows to easily define HTTP API routes.
Independently Deployable Foxx Manager Foxxes run in ArangoDB Coordinators. These are independent from one another. Foxxes can be installed on an arbitrary number of these Coordinators.
Access other Microservices Requests The Foxx request module offers a simple functionality to contact any other API via HTTP.
Scalability Sharding The dataset managed by a Foxx micro-service might be too large for a single server. The underlying ArangoDB infrastructure can handle this for you.
Persistence Repositories Foxx is part of a multi-model database. It has all features to persist data of diverse formats (Graphs, Documents) built-in.
Reuse Services Arango Store The Arango Store contains several Foxxes. Many of them are general-use services that are required in many applications. You can just reuse the reviewed and tested code of other Foxx users.
Automated Deployment Foxx Manager The Foxx manager tool allows to trigger installation of new applications. Also there is a native system HTTP API offering this feature. You can use either one as a step in your build automation tool.
Design for failure Coordinators ArangoDBs cluster setup is designed for failure. You can make use of this feature in your Foxxes.
Different Languages Connect to other APIs Foxxes are only implemented in JavaScript. However not your entire application has to be written in Foxx. You can connect via HTTP to services in other languages.
Different Databases Multi-Model In most setups you need different database technologies because you have several data formats. ArangoDB is a multi-model database that server many formats. However if you still need another database you can connect to it via Http.
Asynchronous Calls Synchronous with multiple contexts Foxx only allows synchronous execution. However it is executed in a multi-threaded fashion, hence blocking one thread is not a problem. Also background tasks are available for long-running tasks that should be executed outside of the request-response cycle.
Security Authentication and Session Foxx offers internal APIs to handle authentication and manage session data. It is just a handful lines of code and your service is secured.
Protected API Libraries Sometimes you have sensitive data that is not allowed to ever leave your database. Using libraries in Foxx you can write internal APIs that can only be accessed from the same server and are not exposed to the outside world. Perfect to keep your data inside but still using the paradigm of a microservice for it.
How To Recipes In ArangoDBs cookbook there are several recipes on how to design a microservice based application with the help of Foxx.
Maintenance UI Built-in Web server ArangoDB has a built-in Web server, allowing Foxxes to ship a Webpage as their UI. So you can attach a maintanance UI directly to your microservice and have it deployed with it in the same step.
Easy Setup ArangoDB on Mesos ArangoDB perfectly integrates with the Mesos project, a distributed kernel written for data centers. You can set up and deploy a Mesos instance running ArangoDB and having your microservice on top of it with just a single command.
Maintenance Marathon If you are running ArangoDB on top of Mesos you can use marathon to keep all your instances alive and scale up or down with just a few clicks. Do not bother with long configuration, that is all handled by the underlying systems.

As you can see most concepts of microservices are natively available in Foxx plus several additions that easy your development process. That is why we like to call Foxx a “data-centric microservice framework”: It allows you to write and deploy data-centric microservices on top of ArangoDB.

How does it work?

The Foxx app is a bundle of JavaScript files with some meta information. The bundle is saved in a special directory on the same server as ArangoDB. The API you created with Foxx is accessible through URLs like And no, this will not expose your entire database unprotected to the world.

Syntax example

With Foxx.Controller you can add your own endpoints to ArangoDB. In the following example we will great users with their own name:

Foxx has support for parsing and checking path, query and body parameters in the controller. It also allows you to convert exceptions thrown in your code to be converted to meaningful HTTP status codes with error messages. But Foxx has more to offer than just Foxx.Controller:

  • Foxx.Repository wraps around collections in ArangoDB so it will be easy for you to save new entries, replace, update and delete them. It also has some simple queries built-in (like searching for documents that match a certain example) and allows you to extend each repository with your own queries (or methods in general).
  • Foxx.Model is a thin wrapper around data which will be generated by the Foxx.Controller and be well understood by Foxx.Repository. It will allow you to add convenience functions to ease your work in other areas.

Documentation as a first class citizen

API documentations are often incomplete or outdated and it’s a struggle to try out if everything works as expected. In Foxx, documentation is a first class citizen:

  • Foxx generates an interactive documentation where you can try out each of the documented endpoints.
  • A lot of documentation is generated automatically from your implementation. Every route will be part of the documentation automatically.
  • With a few more hints from you we can generate a documentation with explanations etc.

So if we annotate our route from above, we will get a full interactive documentation. And information used to verify inputs like type information with the help of the joi library will automatically also be used for documentation:

Getting started

Foxx is part of ArangoDB and so is the Foxx documentation. So first install ArangoDB. Then you can start building your first Foxx app by following our Foxx in 10 Minutes tutorial or the first steps recipe in our Cookbook.
You can also watch Alan’s webinar about Getting started with Foxx:

Foxx Authentication

We also provide a module for authentication with either cookies, API keys or external OAuth providers like Facebook, GitHub or Google. Check out the credential auth or OAuth2 apps for details.

Foxx Job Queues

Foxx allows defining job queues that let you perform slow or expensive actions asynchronously. These queues can be used to send e-mails, call external APIs or perform other actions that you do not want to perform directly or want to retry on failure. You want to send out an email every time a user signs up? No problem! We already have worker types for SendGrid, Postmark, Postage and mailgun. We also have workers for logging errors at bugsnag or to track user activity with After installing and configuring the SendGrid app with your API key for example, you can do the following to send out an email:

Now the email is on its way via SendGrid’s infrastructure – and you did not block the user’s interaction for that to happen. Learn everything about Queues here.

Sample apps

Foxx comes with a couple of sample apps. You can install them via Foxx manager or get a copy directly from Github.


foxx-sessions-example is a demo app how to restrict the access to certain routes using the authentication module. You can log in with external service providers such as GitHub or Twitter.


hello-foxx has basic syntax examples, e.g. on routes, database access, logging, and debugging


aye-aye is an implementation of the famous todo app using Foxx, ArangoDB, and Backbone

Comments are closed.