Reusable Foxx Apps with Configurations: ArangoDB Development

While the optional configuration field in Foxx manifests had experimental support all the way back to ArangoDB 2.1, the feature was previously undocumented and not well understood. The upcoming ArangoDB 2.6 release officially introduces Foxx configurations, allowing you to make your existing Foxx apps more re-usable and to make better use of third-party apps.

Let’s say your Foxx app needs an API key to make a request to a third-party service using the request module introduced in ArangoDB 2.5. Without using configurations, your code might contain the hard-coded API key:

var request = require('org/arangodb/request');
var API_KEY = '4172616e67-6f44422072-6f636b7321';
// ...
controller.post('/bananas', function (req, res) {
 var response =
request.post('https://fruitbar.example.com/api/v2/bananas', {
   headers: {'x-api-key': API_KEY},
   json: req.json()
 });
 // ...
});

This is obviously bad style. If the API key changes we need to update the source code and if we want to re-use the same app with a different API key we have to fork our code base. We also likely end up with credentials in our source control repository, which is a security nightmare.

Luckily we can now adjust our manifest to change that. Just at the following to the app’s manifest.json…

{
 // ...
 "configuration": {
   "apiKey": {
     "description": "Example.com FruitBar API Key",
     "type": "string"
   }
 }
}

…and the configuration value becomes available in our Foxx app as a property of the applicationContext:

var API_KEY = applicationContext.configuration.apiKey;

Note that if you mount a Foxx app for the first time and the app has configuration fields that do not provide default values, you have to configure the app before it becomes active. You can adjust the configuration of your Foxx apps using the foxx-manager CLI from the shell, the web admin frontend in your browser or using the REST API.

If you want to give configurable Foxx apps a try, many of the apps in the Foxx app store already support configuration and can be used in ArangoDB 2.5. If you want to get the full experience, compile the development version of ArangoDB from Github.