ArangoDB Foxx

ArangoDB is extensible with JavaScript. The Foxx framework – which is built into ArangoDB – allows you to do this in a very structured way. Foxx is the simple idea to get an abstraction layer between the database and your apps. It let’s you define your own Web APIs for ArangoDB. Foxx lives inside of ArangoDB, there’s no need to install or deploy something separate. All you need to do is upload your Foxx app to the database.

This is probably a situation you are familiar with: You have one app that talks to your database. But sometimes it makes sense to split your app into multiple parts. Now you have two apps talking to your database. They both do different things. Some data will only be accessed by one app, but there’s also some data that will be accessed by both of them. Now imagine you also need a mobile app – native oder web based. It probably needs to access some Web API to do its job. This API could be embedded in those two apps, but probably you want to handle it separately. Now you have three different apps accessing your database. This of course leads to duplication. Each of those apps needs logic to access the database and get it into the necessary form. There are probably queries written in the databases query language that you will find in each of those apps. A structural change in the data needs to be reflected in each of those apps. That leads to a lot of effort and potential for errors.

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 can be your highly structured Data Abstraction Layer written in JS

Maybe this description reminds you of stored procedures. Foxx is however much more structured and encourages you to encapsulate behavior. This makes your apps resistant to a lot of changes in your schema, so you optimize it without needing to touch all your apps. A Foxx app is stored on your file system, so you can put it under your favorite version control system. Foxx is a framework that helps you structure the data access. And if your Foxx app gets to big, you can split it into multiple ones and run them alongside each other. Foxx is a JavaScript framework. So if you already know JavaScript, you’re good to go. And everything runs inside of ArangoDB. Foxx can be your highly structured Data Abstraction Layer – written in JS. That means that with Foxx you can adapt ArangoDB to your particular needs.

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 http://my-arangodb-host.com:8529/blog/savePosting. 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.

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 Segment.io. 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-apps-foxx-authfoxx-authentication

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.

foxx-apps-hello-foxxhello-foxx

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

foxx-apps-todomvcaye-aye

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

Comments are closed.