arangodb/Documentation/Books/Users/Foxx/README.mdpp

!CHAPTER Foxx
!SUBSECTION 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 
Foxx is Sinatra, [ArangoDB's Actions](../ArangoActions/README.md) are the corresponding *Rack*. 
They provide all the HTTP goodness.

If you just want to install an existing application, please use the 
[Foxx Manager](../FoxxManager/README.md). If you want to create your own application, 
please continue reading.

!SUBSECTION Overview

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.

Think of an Foxx app as a typical web app similar to any other web app using
other technologies. A Foxx app provides one or more URLs, which can either
be accessed directly from the browser or from a backend application written e.g. in
Ruby or C#. Other features include:

* *Routing:* Define arbitrary routes namespaced via the *Controllers*
* *Accesses data:* Direct access to all data in ArangoDB using simple queries, AQL, traversals and more
* *Manipulates data:* Create new or manipulate existing entries
* Deliver *static files* like HTML pages, CSS or images directly

The typical request to a Foxx application will work as follows (only conceptually,
a lot of the steps are cached in reality):

1. The request is routed to a Foxx application depending on the mount point 
2. The according controller of this application is determined (via something called the manifest file)
3. The request is then routed to a specific handler in this controller

The handler will now parse the request. This includes determining all parameters
from the body (which is typically JSON encoded) to the path parameters of the URL.
It is then up to you to handle this request and generate a response. In this process
you will probably access the database. This is done via the *Repository*: This is an
entity that is responsible for a collection and specifically:

1. Creating new entries in this collection
2. Modify or delete existing entries in this collection
3. Search for entries in this collection

To represent an entry in this collection it will use a *Model*, which is a wrapper around
the raw data from the database. Here you can implement helper functions or simple access
methods.

!SUBSECTION Your first Foxx app in 5 minutes

Let's build an application that sends a plain-text response 
"Hello YourName!" for all requests to */dev/my_app/hello/YourName*. 

First, create a directory *apps* somewhere in your filesystem. This will be
the Foxx application base directory for your database instance. Let's assume 
from now on that the absolute path for this directory is */home/user/apps*.
When you have created the directory, create a sub-directory *databases* in it.

Foxx applications are database-specific, and the *databases* sub-directory is
used to separate the Foxx applications of different databases running in the
same ArangoDB instance.

Let's assume for now that you are working in the default database (*_system*), that
is used when no [database name](../Glossary/README.html#database_name) is specified otherwise. To use Foxx applications with
the *_system* database, create a sub-directory *_system* inside the *databases* 
subdirectory. All Foxx applications for the *_system* database will go into this 
directory. Note: to add a Foxx application for a different databases than *_system*, 
use the database's name as the directory name instead of *_system*.

Finally, we can add a sub-directory *my_app* in the *_system* directory and should
end up with the following directory layout (starting at */home/user* in our example):

```
apps/
  databases/
    _system/
      my_app/
```

In the *my_app* directory, create a file named *app.js* and save the following content
in it:

```js
(function() {
    "use strict";

    var Foxx = require("org/arangodb/foxx"),
        controller = new Foxx.Controller(applicationContext)

    controller.get("/hello/:name", function(req, res) {
        res.set("Content-Type", "text/plain");
        res.body = "Hello " + req.params("name");
    }); 

}());
```

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:

```js
{
  "name": "my_app",
  "version": "0.0.1",
  "author": "me and myself",
  "controllers": {
    "/": "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):

```js
apps/
  databases/
    _system/
      my_app/
        manifest.json
        app.js
```

This is your application, and you're ready to use it.

!SUBSECTION Testing the application

Start ArangoDB as follows:

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

If you chose a different directory name, you need to replace */home/user/apps* 
with the actual directory name of course. Replace */tmp/fancy_db* with the
directory your database data is located in.

The command will start the ArangoDB server in a **development mode** using the
directory */home/user/apps* as the workspace and */tmp/fancy_db* as your
database directory.  In development mode the server automatically reloads all
application files on every request, so changes to the underlying files are
visible instantly. 
Note: if you use the development mode for the first time or choose a different
directory for *dev-app-path*, it may be necessary to start ArangoDB with the
*--upgrade* option once. This will initialize the specified application directory.

**Note**: the development mode is convenient when developing applications but the
permanent reloading has an impact on performance. Therefore permanent reloading is
only performed in development mode and not in production mode. Whenever you think 
your application is ready for production, you can install it using the Foxx manager
and avoid the overhead of reloading.

Now point your browser to *localhost:8529/dev/my_app/hello/YourName* and you should 
see "Hello YourName". 

**Note**: the above and all following examples assume that you are using the default 
database (*_system*).If you use a different database than *_system*, URLs must be 
changed to include the database name, too. For example, if your database name is 
*mydb*, the above URL changes to *localhost:8529/_db/mydb/dev/my_app/hello/YourName*. 
For more information on how to access specific databases, please refer to 
[Address of a Database](../HttpDatabase/README.md). 

After this short overview, let's get into the details. There are several example
apps available on Github. You can install them via Foxx manager (covered in the
chapter on Foxx manager) or simply clone them from [github](https://github.com/arangodb/).

Start with ["hello-foxx"](https://github.com/arangodb/hello-foxx) as it contains
several basic usage examples. ["aye-aye"](https://github.com/arangodb/aye-aye)
and ["fugu"](https://github.com/arangodb/aye-aye) are more advanced apps showing how
to use Backbone, Underscore and Jquery together with Foxx. ["foxx-authentication"](https://github.com/arangodb/foxx-authentication)
shows how to register users, log in and check permissions.