16 KiB

Raw Blame History

Foxx

@NAVIGATE_UserManualFoxx @EMBEDTOC{UserManualFoxxTOC}

Foxx: Build APIs and simple web applications in ArangoDB

Foxx is an easy way to create APIs and simple web applications from within ArangoDB. It is inspired by Sinatra, the classy Ruby web framework. If FoxxApplication is Sinatra, @ref UserManualActions are the corresponding Rack. They provide all the HTTP goodness.

If you just want to install an existiting application, please use the @ref UserManualFoxxManager. If you want to create your own application, please continue.

So let's get started, shall we?

Creating the application files

An application built with Foxx is written in JavaScript and deployed to ArangoDB directly. ArangoDB serves this application, you do not need a separate application server.

So given you want to build an application that sends a plain-text response "Worked!" for all requests to /dev/meadow. How would you achieve that with Foxx?

First, create a directory apps somewhere in your filesystem. Let's assume from now on that the absolute path for this directory is /home/user/apps.

After that, create a sub-directory my_app in the apps directory and save the following content in a file named app.js there:

var Foxx = require("org/arangodb/foxx");
var app = new Foxx.Application(applicationContext);

app.get("/meadow", function(req, res) {
  res.set("Content-Type", "text/plain");
  res.body = "Worked!"
});

Beside the app.js we need a manifest file. In order to achieve that, we create a file called manifest.json in our my_app directory with the following content:

{
  "name": "my_app",
  "version": "0.0.1",
  "author": "me and myself",
  "apps": {
    "/": "app.js"
  }
}

You must specify a name and a version number for your application, otherwise it won't be loaded into ArangoDB.

You should now have the following files and directories with your application (starting at /home/user in our example):

apps/
  my_app/
    manifest.json
    app.js

This is your application.

Testing the application

Now your application is ready to be tested. Start ArangoDB as follows:

$ arangod --javascript.dev-app-path /home/user/apps /tmp/fancy_db

This will start the ArangoDB server in a development mode using the directory /home/user/apps as workspace. Produktion application are installed using the Foxx manager and should not be changed. In development mode the server automatically monitors the workspace and detects any change made to the files.

Replace /home/user/apps with the apps path that you initially created. This is the path that you created the my_app directory in. Replace /tmp/fancy_db with the directory your database is located in.

Now point your browser to http://localhost:8529/dev/meadow and you should see "Worked!". After this short overview, let's get into the details.

Handling Requests

In development mode all available applications from the application directory /home/user/apps are visible under http://localhost:8529/dev/DIRNAME where DIRNAME is the name of the directory of your application.

When applications are imstalled in production mode, you can change the /dev prefix to whatever you like, see @ref UserManualFoxxManager.

If you do not redefine it, all requests that go to the root of your application will be redirected to index.html.

Details on FoxxApplication

@copydetails JSF_foxx_application_initializer

@CLEARPAGE @copydetails JSF_foxx_application_createRepository

@CLEARPAGE HTTP Methods

@copydetails JSF_foxx_application_get

@CLEARPAGE @copydetails JSF_foxx_application_head

@CLEARPAGE @copydetails JSF_foxx_application_post

@CLEARPAGE @copydetails JSF_foxx_application_put

@CLEARPAGE @copydetails JSF_foxx_application_patch

@CLEARPAGE @copydetails JSF_foxx_application_delete

@CLEARPAGE Documenting and Constraining the Routes

If you define a route like described above, you have the option to match parts of the URL to variables. If you, for example, define a route /animals/:animal and the URL animals/foxx is requested it is matched by this rule. You can then get the value of this variable (in this case "foxx") by calling request.params("animal").

Furthermore you can describe your API by chaining the following methods onto your path definition. With the provided information, Foxx will generate a nice documentation for you. Some of the methods additionally will check certain properties of the request.

@copydetails JSF_foxx_RequestContext_pathParam

@CLEARPAGE @copydetails JSF_foxx_RequestContext_queryParam

@CLEARPAGE @copydetails JSF_foxx_RequestContext_summary

@CLEARPAGE @copydetails JSF_foxx_RequestContext_notes

@CLEARPAGE @copydetails JSF_foxx_RequestContext_errorResponse

@CLEARPAGE Before and After Hooks

You can use the following two functions to do something before or respectively after the normal routing process is happening. You could use that for logging or to manipulate the request or response (translate it to a certain format for example).

@copydetails JSF_foxx_application_before

@CLEARPAGE @copydetails JSF_foxx_application_after

@CLEARPAGE More functionality

@copydetails JSF_foxx_application_helper

@CLEARPAGE @copydetails JSF_foxx_application_accepts

@CLEARPAGE The Request and Response Objects

When you have created your FoxxApplication you can now define routes on it. You provide each with a function that will handle the request. It gets two arguments (four, to be honest. But the other two are not relevant for now):

The request object
The response object

These objects are provided by the underlying ArangoDB actions and enhanced by the BaseMiddleware provided by Foxx.

The Request Object

Every request object has the following attributes from the underlying Actions, amongst others:

@FUN{request.path}

This is the complete path as supplied by the user as a String.

@CLEARPAGE @copydetails JSF_foxx_BaseMiddleware_request_body

@CLEARPAGE @copydetails JSF_foxx_BaseMiddleware_request_params

@CLEARPAGE The Response Object

Every response object has the following attributes from the underlying Actions:

@FUN{response.body}

You provide your response body as a String here.

@CLEARPAGE @copydetails JSF_foxx_BaseMiddleware_response_status

@CLEARPAGE @copydetails JSF_foxx_BaseMiddleware_response_set

@CLEARPAGE @copydetails JSF_foxx_BaseMiddleware_response_json

@CLEARPAGE @copydetails JSF_foxx_BaseMiddleware_response_render

@CLEARPAGE Details on FoxxModel

The model doesn't know anything about the database. It is just a representation of the data as an JavaScript object. You can add and overwrite the methods of the prototype in your model prototype via the object you give to extend. In your model file, export the model as model.

var Foxx = require("org/arangodb/foxx");

var TodoModel = Foxx.Model.extend({
});

exports.model = TodoModel;

A Foxx Model can be initialized with an object of attributes and their values.

@copydetails JSF_foxx_model_extend

@CLEARPAGE @copydetails JSF_foxx_model_initializer

@CLEARPAGE @copydetails JSF_foxx_model_get

@CLEARPAGE @copydetails JSF_foxx_model_set

@CLEARPAGE @copydetails JSF_foxx_model_has

@CLEARPAGE @FUN{FoxxModel::attributes}

The attributes property is the internal hash containing the model's state.

@CLEARPAGE @copydetails JSF_foxx_model_forDB

@CLEARPAGE @copydetails JSF_foxx_model_forClient

@CLEARPAGE Details on FoxxRepository

A repository is a gateway to the database. It gets data from the database, updates it or saves new data. It uses the given model when it returns a model and expects instances of the model for methods like save. In your repository file, export the repository as repository.

Foxx = require("org/arangodb/foxx");

TodosRepository = Foxx.Repository.extend({
});

exports.repository = TodosRepository;

@copydetails JSF_foxx_repository_initializer

@CLEARPAGE @FUN{FoxxRepository::collection}

The collection object.

@CLEARPAGE @FUN{FoxxRepository::prefix}

The prefix of the application.

@CLEARPAGE @FUN{FoxxRepository::modelPrototype}

The prototype of the according model.

@CLEARPAGE @FUN{FoxxRepository::save}