Crawling GitHub with Promises: ArangoDB Tutorial

The new Javascript driver no longer imposes any promises implementation. It follows the standard callback pattern with a callback using err and res.

I wanted to give the new driver a try. A github crawler seemed like a good side-project, especially because the node-github driver follows the same conventions as the Javascript driver.

There are a lot of promise libraries out there. The most popular one – according to NPM – was promises. It should be possible to use any implementation. Therefore I used this one.


More info...

Getting Started with Guacamole in Rails: ArangoDB Tutorial

Please note that parts of this article will not work out of the box with ArangoDB 3.0

Using ArangoDB as your main database is a good idea for various reasons. What I personally like about it is its query language AQL. I used relational databases in the past as my main database and writing statements in a language similar to SQL was a great way for me to get started with ArangoDB.

Having a HTTP based interface (like all the cool kids these days) we could build applications running solely on top of our database. That’s rather nice but then we would have to take care of all the gory details. So for our app we want at least an abstraction layer on top of the HTTP API. Better yet, something assisting us with modeling our domain logic.

Meet Guacamole: A object-document-mapper that takes care of all the busywork and allows you to focus on your domain. (more…)

More info...

Building Hypermedia APIs with FoxxGenerator: ArangoDB Tutorial

This is the third and final part of Lucas blog series about building hypermedia APIs. In the previous part, we identified the needed transitions and collected some information about each of them. Begin with blog post one to get familiar with concepts on Hypermedia and JSON.

We can now describe the identified transitions using FoxxGenerator. To make the most common case simple, it defaults to the type follow. Therefore defining our four follow transitions is easy using FoxxGenerator:


Note that at this point we are just defining the transitions, we are not adding them to the statemachine we are describing with the help of FoxxGenerator. In the case of creating a book, we need to add additional information. First of, it is a connect transition. Secondly we also need to define the parameters that this transition needs:

generator.defineTransition('createBook', {
  type: 'connect',

  parameters: {
    title: Joi.string()


More info...

Building Hypermedia APIs: Design Principles & Best Practices

This is the second blog post on building hypermedia APIs with the focus on API design. In part 1 Lucas describes the concept of links in JSON.

Imagine we have an API where people can like books and other people can then see, who likes a certain book. We want this API to be highly connected: We don’t want to look up URLs in a documentation, we want to follow links as we know it from the world wide web. All we want to do as the author of the API is give our users a single URL from which they can then follow links to all other resources. This is similar to the way we would do this with a website. Leonard Richardson and Mike Amundsen refer to this as the billboard URL for this reason: If you put this URL on some billboard, people know everything to get started with your API. (more…)

More info...

Building a Hypermedia API with JSON: ArangoDB Tutorial

When we create websites we don’t just create single pages that have no connection to other Web pages. From the beginning, hyperlinks were part of the core concept of the World Wide Web and for that reason HTML. Links are so essential to the Web that they are even used to rank the popularity of the Web pages on search engines. And who hasn’t gone on a journey through Wikipedia clicking link after link? Even though we all know and appreciate the importance of links on Websites, we rarely use links in our Web APIs. (more…)

More info...

Getting Started with ArangoDB & Symfony: Part 1 | ArangoDB 2013

This is part 1 (of 4) of an introduction to the use of ArangoDB together with Symfony 2. You'll find the links to the other parts of this tutorial at the end of this text.

In this tutorial we will implement a very simple movie database as an example of how to use ArangoDB together with Symfony 2. We assume for the tutorial that you know the basic concepts of Symfony2. No prior ArangoDB knowledge is required.

The demo shows how to create, edit, update and delete movies, how to select a list of movies from the database in two different ways. We’ll use the simple query API for most examples. The “search for a topic” feature uses ArangoDB’s query language (AQL), a convenient sql-like way to query ArangoDB.

You can download the completed demo at Github.

A short word on ArangoDB

Warning - a paragraph of marketing ahead! ;-) ArangoDB is an open-source mostly-memory database with a flexible data model for documents and graphs for modern web applications.  With ArangoDB you build high performance applications in short time - it is schema-less and has a full-blown query language nevertheless (there is no need to write map/reduce functions if your queries get more complicate) . You can even extend ArangoDB by adding your own Javascript/Ruby methods to the database.

Libraries & infrastructure

The following components are used

What’s this? Since Symfony is a PHP framework we need the PHP driver for ArangoDB. The MopArangoDbBundle integrates the PHP driver into Symfony: having this bundle installed, you can config the connection to ArangoDB in the config.yml (note: the bundle also offers a FOSUserBundle integration which is not used in this demo, but might be interested for you if you are looking for a  user management system out of the box).

Installing ArangoDB

Now grab your copy of ArangoDB from the download page and install it. There are binaries available for many common platforms (Linux, OSX, Windows). Make sure that ArangoDB is up and running by opening the graphical user interface in your browser:


Configuring Symfony for use with ArangoDB

First thing we have to do is to tell Symfony that we want to work with ArangoDB. So we add the two required bundles to composer.json and run “php composer.phar update” as usual.

// path/to/myapp/composer.json
"require": {
        "triagens/ArangoDb": "dev-devel",
        "mop/arangodbbundle" : "dev-master"

Note: for this tutorial a feature was added to the ArangoDB PHP driver which is only available in the  “dev-devel” branch at the time of writing this text.

Having MopArangodbBundle installed we can add our connection settings to config.yml

    default_connection: main #will be set to the first connection if not present
            port: 8529

We are done.

In Symfony we can now access the default connection to ArangoDB with

$connection = $this->get('mop_arangodb.default_connection');

The end

Congrats, you have reached the end of part 1 the tutorial. There is more:

More info...

ArangoDB & Symfony Integration: Part 2 | ArangoDB ’13

This is part 2 (of 4) of an introduction to the use of ArangoDB together with Symfony 2. You’ll find the links to the other parts of this tutorial at the end of this text.

You can download the completed demo at Github.

The data structure

Our app deals with movies: each movie has a title, a year of release and it is assigned to a genre. Each movie deals with none, one or many topics.

In a relational database we would probably create a table movie and another table topic and join them with a shared movie id.

ArangoDB follows like other document stores the “aggregate model” approach: In short terms this means that you should put data that is often needed together into one document. Remember: documents are a bit like rows in the relation world; in nosql world they can have a nested structure.


More info...

ArangoDB & Symfony Integration: Part 3 Guide | ArangoDB ’13

This is part 3 (of 4) of an introduction to the use of ArangoDB together with Symfony 2. You’ll find the links to the other parts of this tutorial at the end of this text.
You can download the completed demo at Github.

Working with forms

The next example shows the use of ArangoDB with Symfony’s form component.

This is how our form will look like. The topics are represented as a text field and the user is required to separate them by commas. This delivers questionable user experience, but leads to an interesting question: how can we transform our topics array from our movie document to a text field? And: we’ll need it at least two times, both for creating and editing movies.


More info...

ArangoDB & Symfony Integration: Part 4 Guide | ArangoDB ’13

This is part 4 (of 4) of an introduction to the use of ArangoDB together with Symfony 2. You’ll find the links to the other parts of this tutorial at the end of this text.
You can download the completed demo at Github.

Extending Arangodb\Document

The next thing we want to improve are all those noisy set calls in the controller:

// src/Triagens/ArangodbBundle/Controller/DefaultController.php
if ($form->isValid()) {
    $movie = new ArangoDocument();
    // and so on ... my eyes hurt!


More info...

API Implementors Gathering: ArangoDB 2013

Dear API Implementors,

We want to make it simpler for you to keep up with the development of ArangoDB. We therefore created a dedicated place for all API implementors. If you are implementing a Driver, ODM or database access tool for ArangoDB, this is the right place for you. In addition to sharing information about the changing API, we want to discuss patterns and ideas with each other.

The team behind ArangoDB will announce API changes and enhancements in the issues of this project, so you have one place to get all the up to date information. Apart from that, the community is independent from the ArangoDB team.

We want to make this a central, open place for all API implementors. So if you want to be part of this group, just introduce yourself and we will add you to the list. Then just watch the Repository to get all information in your inbox.

We already have the people behind the PHP and Ruby drivers on board. We’re looking forward to discussing with you and build a multi-programming language community around ArangoDB. So join us.

More info...

Get the latest tutorials,
blog posts and news: