Introducing the Neo4j REST interface

Neo4j exposes a variety of REST APIs for performing the CRUD operations. It also provides various endpoints for the search and graph traversals. Neo4j 2.2.x provides the additional feature of securing the REST endpoints.

Let's move forward and see a step-by-step process to access and execute the REST APIs for performing the CRUD operations.

Authorization and authentication

In order to prevent unauthorized access to endpoints, Neo4j 2.2.x, by default, provides token-based authorization and authentication for all the REST endpoints.

Therefore, before running any CRUD operations, we need to get the security token so that every request is authenticated and authorized by the Neo4j server.

Let's perform the following steps for getting the token:

1. Open your UNIX shell/console and execute <$NEO4J_HOME>/bin/neo4j start to start your Neo4j server, in case it is not running.
2. Download any tool such as SOAP-UI (http://www.soapui.org/), which provides the creation and execution of the REST calls.
3. Open your tool and execute the following request and parameters for creating data in the Neo4j database:
   • Request method type: POST
   • Request URL: http://localhost:7474/authentication
   • Request headers: Accept: application/json; charset=UTF-8 and Content-Type: application/json
   • Additional HTTP header: Authorization= Basic <base64(username:password)>
4. In the preceding request, replace <base64(username:password)> with the base64 encoded string for username:password. This username is the default username, neo4j, and the password is the real password, which was provided/changed when you accessed your Neo4j browser for the first time.
5. For example, the base64 encoded string for username, neo4j, and password, sumit, will be bmVvNGo6c3VtaXQ=, so now your additional HTTP header will be something like the following:

   Authorization = Basic bmVvNGo6c3VtaXQ=

   

The preceding screenshot shows the format of the request along with all the required parameters for authorizing the REST-based request to the Neo4j server.

You can also switch off the authentication by modifying dbms.security.authorization_enabled=true in $NEO4J_HOME/conf/neo4j-server.propoerties. Restart your server after modifying the property.

Now, as we have a valid token, let's move ahead and execute various CRUD operations.

Note

For converting in base64, you can use the online utility at http://www.motobit.com/util/base64-decoder-encoder.asp or you can also use the Python base64 library at https://docs.python.org/2/library/base64.html.

CRUD operations

Create, read, update, and delete are the four basic and most common operations for any persistence storage. In this section, we will talk about the process and syntax leveraged by Neo4j to perform all these basic operations.

Perform the following steps for creating, searching, and deleting data in the Neo4j database:

1. Download any tool such as SOAP-UI (http://www.soapui.org/), which provides the creation and execution of the REST calls.
2. Open your tool and execute the following request and parameters for creating data in the Neo4j database:
   • Request method type: POST
   • Request URL: http://localhost:7474/db/data/transaction
   • Request headers: Accept: application/json; charset=UTF-8 and Content-Type: application/json
   • JSON-REQUEST: {"statements": [{"statement" : "CREATE (movies:Movie {Name:"Noah", ReleaseYear:"2014"});"}]}
   • Additional HTTP header: Authorization = Basic <base64(username:password)>
3. Replace <base64(username:password)> with the actual base64 token, which we generated in the Authorization and Authentication section, and execute the request. You will see no errors and the output will look something like the following screenshot:
   

   In the preceding screenshot, the CREATE request created a label Movie with two attributes, Name and ReleaseYear

4. Next, let's search the data, which we created in the previous example. Open your tool and execute the following request and parameters for searching data in the Neo4j database:
   • Request method type: POST
   • Request URL: http://localhost:7474/db/data/transaction
   • Request Headers: Accept: application/json; charset=UTF-8 and Content-Type: application/json
   • JSON-REQUEST: {"statements": [{"statement" : "MATCH (n) return n;"}]}
   • Additional HTTP Header: Authorization = Basic <base64(username:password)>
5. Replace <base64(username:password)> with the actual base64 token, which we generated in the Authorization and Authentication section and execute the request. You will see no errors and the output will look something like the following screenshot:
   

   In the preceding screenshot, the MATCH request searched the complete database and returned all the nodes and their associated properties.

6. Next, let's delete the data, which we searched in the preceding step. Open your tool and execute the following request and parameters for search, and then delete the data from the Neo4j database in a single Cypher statement:
   • Request method type: POST
   • Request URL: http://localhost:7474/db/data/transaction/commit
   • Request headers: Accept: application/json; charset=UTF-8 and Content-Type: application/json
   • JSON-REQUEST: {"statements": [{"statement" : "MATCH (n) delete n;"}]}
   • Header-Parameter: Authorization = Basic realm="Neo4j" <BASE64-ENCODED-TOKEN>
7. Replace <BASE64-ENCODED-TOKEN> with the actual base64 token, which we generated in the Authorization and Authentication section, and execute the request. The response of the delete request will be same as the Create request.

In this section, we walked through the process of executing the Cypher queries with one of the REST endpoints, /db/data/transaction/commit, which is known as Transactional Cypher HTTP Endpoint. There are various other REST endpoints exposed by Neo4j for performing traversals, search, CRUD, administration, and a health check of the Neo4j server. Refer to http://neo4j.com/docs/stable/rest-api.html for a complete list of available endpoints, or you can also execute another REST point exposed by Neo4j, /db/data, which is known as the service root and the starting point to discover the REST API. It contains the basic starting points for the database along with some version and extension information.

Note

Linux users can also use the curl command to create and retrieve the data using the Neo4j REST APIs (http://neo4j.com/blog/the-neo4j-rest-server-part1-get-it-going/).