The Neo4j REST Server – Part1: Get it going!

Introduction

As requested and wished by many, finally Neo4j got its own standalone server mode, based on interaction via REST. The code is still very fresh and not thoroughly tested, but I thought I might write up some first documentation on it, based on the Getting Started with REST Wiki page

Installation

The first version of the distribution can be downloaded from here: zip, tar.gz. After unpacking, you just go to the unpacked directory and run (on OSX/Linux – see the wiki entry for details on Windows)

$ ./bin/neo4j-rest start

which will start the Neo4j REST server at port 9999 and put the database files under a directory neo4j-rest-db/ (lazily with the first request). Now, let’s point our browser (not Internet Explorer since it doesn’t send any useful Accept-headers and will get JSON back, this will be fixed later) to http://localhost:9999 and we will see the following:

Things seem to be running! The reason for the HTML interface is the Browser sending Accept: text/html. Now, setting the Accept to application/json will produce

Resulting in a new node with the URL localhost:9999/node/1 (described by the “self” property in the JSON representation) and no properties set (“data”:{}). The Neo4j REST API is really trying to be explicit about possible further destinations, making it self-describing even for new users, and of course abstracting away the server instance in the future. This makes dealing with multiple Neo4j servers easier in the future. We can see the URIs for traversing, listing properties and relationships. The PUT semantics on properties work like for nodes.We delete the node again with

curl -X DELETE -v localhost:9999/node/1

and get 204 - No Content back. The Node is gone and will give a 404 - Not Found if we try to GET it again.

The Matrix

Now with properties encoded in JSON we can easily start to create our little Matrix example:

In order to create relationships, we do a POST on the originating Node and post the relationship data along with the request (escaping the whitespaces and others special characters):

Now, pointing our browser at http://localhost:9999/node/3/relationships/all will list all relationships of Trinity:

Our first traversal

To start with, the Neo4j default Traverser framework (updated to be more powerful than the current) is supported in REST, and other implementations like Gremlin and Pipes to follow. The documentation on the traversals is in the making here. There are a number of different parameters:http://localhost:9999/node/3/traverse/node specifies a return type of “node”, returning node references. There are other return types such as relationship, position and path returning other interesting info respective. The Traverser description is pluggable and has default values – a full description looks like

To note here is the pluggable description of the “return filter” (what to include in the return) and “prune evaluator” (where to stop traversing). Right now only JavaScript is supported for writing these more complicated constructs up, but other languages are coming. Very cool. To finish, let’s get all the nodes at depth 1 from Trinity via trivial traversal:

Which just returns all nodes of all relationships types at depth one (default) as a JSON Array of node descriptions as above, in this case http://localhost:9999/node/1 and http://localhost:9999/node/2.

Summary

Having the Neo4j REST API and with it the Neo4j REST Server coming along is great news for all that want to use a graph database over the network, especially PHP or .NET clients that have no good Java bindings. Already a first client wrapper for .NET by Magnus Mårtensson from Jayway is underway, and a first PHP client is on Al James’ GIThub.This will even pave the way for higher-level sharding and distribution scenarios and can be used in many other ways. Stay tuned for a deeper explanation of the different traversal possibilities with Neo4j and REST in a next post!

Want to learn more about graph databases? Click below to get your free copy of O’Reilly’s Graph Databases ebook and discover how to use graph technologies for your application today.Download My Ebook

Is there a way to configure the port? Cloud services depend on dynamic ports, so the port is not known until the VM is allocated (then your public port, most likely 80, is bound to the internal dynamic port).<br /><br />I think just a simple war would have sufficed, but I applaud the intent to make running neo4j simple.<br /><br />Taylor

Hi Taylor, the port isn&#39;t configurable at the moment and it&#39;s just because we haven&#39;t got to it yet. It&#39;s still considered in alpha state.<br /><br />However I think it&#39;s a minor fix and I&#39;ll look into it as soon as I get the time for it!

I wasn&#39;t able to get the snapshots working under a 64-bit ubuntu machine. I get a strange error:<br /><br />Starting Neo4j REST Server…<br />eval: 1: /usr/local/src/neo4j-rest-standalone-0.8-SNAPSHOT/bin/./wrapper-linux-x86-32: not found<br /><br />I assure you that the wrapper-linux-x86-32 wrapper is there:<br /><br />in/wrapper-linux-x86-32: ELF 32-bit LSB executable, Intel 80386, version

@Lox: I have updated the snapshots (same links as before) to include a 64-bit wrapper for Linux. This may be needed on some systems. If there still are problems, try to remove the 32-bit wrapper from the bin directory as well.

I had some problems to setup Neo4j in Linux in order to code in Python, so I decided to use the new Neo4j REST Server.<br />However, WADL is too much hard and its syntax in python wadllib hasn&#39;t compatibility with current ne4j.py syntax. Thus, I decided to start a implementation of Neo4j Python REST Client: http://github.com/versae/neo4j-rest-client<br />It&#39;s a pre-alpha status, but I

Just wondering, what is the performance of this REST api like? Do the HTTP requests add a lot of latency in your experience? I&#39;m new to Neo4J, but one of the themes I&#39;ve seen is that it&#39;s very fast. That&#39;s one of the reasons I&#39;m looking into it. But I want to connect to it from a native Ruby application (not in jRuby) and it seems like REST is the only option. With speed

@Dough Huges: actually CRuby support is coming along in the <a href="http://github.com/andreasronge/neo4j/tree/rjb&quot; rel="nofollow">rjb branch</a>.<br /><br />Regarding performance over REST, I haven&#39;t seen any numbers yet. By exposing a domain-centric REST API instead of using the standard REST component you should be able to reduce the &quot;chattiness&quot; of the communication (this of

Neo4j guys should take a look Apache SOLR for an easy to use, high performance REST api (the json version of it). It&#39;s very easy to bind to any dynamic languages (python/ruby/js), allows for bulk operations (bulk adding data with few requests), and is generally very nicely done. <br />All this custom HTTP method stuff with lack of bulk operation support largely reduces the usability of the

Hi all!<br />When I run on ubuntu server 11.04 command:<br />$ ./bin/neo4j-rest start <br />I have the folowing problem:<br />Unable to lacate any of folowing binaries:<br />/home/wonder/neo4j/neo4j-rest/bin/./wrapper-linux-x86-32 (Found but not executable.)<br />/home/wonder/neo4j/neo4j-rest/bin/./wrapper-linux-x86-64 (Found but not executable.)<br />/home/wonder/neo4j/neo4j-rest/bin/./wrapper<