Skip to content

Latest commit

 

History

History
491 lines (402 loc) · 16.3 KB

README.adoc

File metadata and controls

491 lines (402 loc) · 16.3 KB
Raw
Table of Contents

This guide walks you through the process of creating an application that accesses graph-based data through a hypermedia-based RESTful front end.

What You Will Build

You will build a Spring application that lets you create and retrieve Person objects that are stored in a Neo4j NoSQL database by using Spring Data REST. Spring Data REST takes the features of Spring HATEOAS and Spring Data Neo4j and automatically combines them together.

Note
 Spring Data REST also supports Spring Data JPA, Spring Data Gemfire, and Spring Data MongoDB as backend data stores, but this guide deals with Neo4j.

Standing up a Neo4j Server

Before you can build a this application, you need to set up a Neo4j server.

Neo4j has an open source server that you can install for free.

On a Mac with Homebrew installed, you can type the following in a terminal window:

$ brew install neo4j

Once you have installed Neo4j, you can launch it with its default settings by running the following command:

$ neo4j start

You should see a message similar to the following:

Starting Neo4j.
Started neo4j (pid 96416). By default, it is available at http://localhost:7474/
There may be a short delay until the server is ready.
See /usr/local/Cellar/neo4j/3.0.6/libexec/logs/neo4j.log for current status.

By default, Neo4j has a username and password of neo4j and neo4j. However, it requires that the new account password be changed. To do so, run the following command:

$ curl -v -u neo4j:neo4j POST localhost:7474/user/neo4j/password -H "Content-type:application/json" -d "{\"password\":\"secret\"}"

This changes the password from neo4j to secret (something to NOT DO in production!) With that completed, you should be ready to run this guide.

Starting with Spring Initializr

You can use this pre-initialized project and click Generate to download a ZIP file. This project is configured to fit the examples in this tutorial.

To manually initialize the project:

  1. Navigate to https://start.spring.io. This service pulls in all the dependencies you need for an application and does most of the setup for you.

  2. Choose either Gradle or Maven and the language you want to use. This guide assumes that you chose Java.

  3. Click Dependencies and select Rest Repositories and Spring Data Neo4j.

  4. Click Generate.

  5. Download the resulting ZIP file, which is an archive of a web application that is configured with your choices.

Note
 If your IDE has the Spring Initializr integration, you can complete this process from your IDE.
Note
 You can also fork the project from Github and open it in your IDE or other editor.

Permissions to Access Neo4j

Neo4j Community Edition requires credentials to access it. You can configure the credentials by setting properties in src/main/resources/application.properties, as follows:

link:complete/src/main/resources/application.properties[role=include]

This includes the default username (neo4j) and the newly set password (secret) that you set earlier.

Warning
 Do NOT store real credentials in your source repository. Instead, configure them in your runtime by using Spring Boot’s property overrides.

Create a Domain Object

You need to create a new domain object to present a person, as the following example (in src/main/java/com/example/accessingneo4jdatarest/Person.java) shows:

link:complete/src/main/java/com/example/accessingneo4jdatarest/Person.java[role=include]

The Person object has a first name and a last name. There is also an ID object that is configured to be automatically generated so that you need not do so.

Create a Person Repository

Next, you need to create a simple repository, as the following example (in src/main/java/com/example/accessingneo4jdatarest/PersonRepository.java) shows:

link:complete/src/main/java/com/example/accessingneo4jdatarest/PersonRepository.java[role=include]

This repository is an interface and lets you perform various operations that involve Person objects. It gets these operations by extending the PagingAndSortingRepositry interface defined in Spring Data Commons.

At runtime, Spring Data REST automatically creates an implementation of this interface. Then it uses the @RepositoryRestResource annotation to direct Spring MVC to create RESTful endpoints at /people.

Note
 @RepositoryRestResource is not required for a repository to be exported. It is used only to change the export details, such as using /people instead of the default value of /persons.

Here you have also defined a custom query to retrieve a list of Person objects based on the lastName value. You can see how to invoke it later in this guide.

Finding the Application Class

The Spring Initializr creates an application class when you use it to create a project. You can find that in src/main/java/com/example/accessingneo4jdatarest/Application.java. Note that the Spring Initializr concatenates (and properly changes the case of) the package name and adds it to Application to create the application case name. In this case, we get AccessingNeo4jDataRestApplication, as the following listing shows:

link:complete/src/main/java/com/example/accessingneo4jdatarest/AccessingNeo4jDataRestApplication.java[role=include]

You need not make any changes to this application class for this example

The @EnableNeo4jRepositories annotation activates Spring Data Neo4j. Spring Data Neo4j creates a concrete implementation of the PersonRepository and configures it to talk to an embedded Neo4j database by using the Cypher query language.

Logging output is displayed. The service should be up and running within a few seconds.

Test the Application

Now that the application is running, you can test it. You can use any REST client you wish. The following examples use the *nix tool called curl.

First, you want to see the top level service. The following example (with output) shows how to do so:

$ curl http://localhost:8080
{
  "_links" : {
    "people" : {
      "href" : "http://localhost:8080/people{?page,size,sort}",
      "templated" : true
    }
  }
}

Here you get a first glimpse of what this server has to offer. There is a people link located at http://localhost:8080/people. It has some options such as ?page, ?size, and ?sort.

Note
 Spring Data REST uses the HAL format for JSON output. It is flexible and offers a convenient way to supply links adjacent to the data that is served. 
$ curl http://localhost:8080/people
{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people{?page,size,sort}",
      "templated" : true
    },
    "search" : {
      "href" : "http://localhost:8080/people/search"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}

There are currently no elements and, consequently, no pages, so it is time to create a new Person! To do so, run the following command (shown with its output):

$ curl -i -X POST -H "Content-Type:application/json" -d '{  "firstName" : "Frodo",  "lastName" : "Baggins" }' http://localhost:8080/people
HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
Location: http://localhost:8080/people/0
Content-Length: 0
Date: Wed, 26 Feb 2014 20:26:55 GMT

  • -i ensures you can see the response message including the headers. The URI of the newly created Person is shown

  • -X POST signals this a POST used to create a new entry

  • -H "Content-Type:application/json" sets the content type so the application knows the payload contains a JSON object

  • -d '{ "firstName" : "Frodo", "lastName" : "Baggins" }' is the data being sent

Note
 Notice how the previous POST operation includes a Location header. This contains the URI of the newly created resource. Spring Data REST also has two methods (RepositoryRestConfiguration.setReturnBodyOnCreate(…) and setReturnBodyOnCreate(…)) that you can use to configure the framework to immediately return the representation of the resource that was just created.

From this you can query for all people by running the following command (shown with its output):

$ curl http://localhost:8080/people
{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people{?page,size,sort}",
      "templated" : true
    },
    "search" : {
      "href" : "http://localhost:8080/people/search"
    }
  },
  "_embedded" : {
    "people" : [ {
      "firstName" : "Frodo",
      "lastName" : "Baggins",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/people/0"
        }
      }
    } ]
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

The people object contains a list with Frodo. Notice how it includes a self link. Spring Data REST also uses the Evo Inflector library to pluralize the name of the entity for groupings.

You can query directly for the individual record by running the following command (shown with its output):

$ curl http://localhost:8080/people/0
{
  "firstName" : "Frodo",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/0"
    }
  }
}
Note
 This might appear to be purely web based, but, behind the scenes, there is an embedded Neo4j graph database. In production, you would probably connect to a standalone Neo4j server.

In this guide, there is only one domain object. With a more complex system, where domain objects are related to each other, Spring Data REST renders additional links to help navigate to connected records.

You can find all the custom queries by running the following command (shown with its output):

$ curl http://localhost:8080/people/search
{
  "_links" : {
    "findByLastName" : {
      "href" : "http://localhost:8080/people/search/findByLastName{?name}",
      "templated" : true
    }
  }
}

You can see the URL for the query, including the HTTP query parameter: name. Note that this matches the @Param("name") annotation embedded in the interface.

To use the findByLastName query, run the following command (shown with its output):

$ curl http://localhost:8080/people/search/findByLastName?name=Baggins
{
  "_embedded" : {
    "people" : [ {
      "firstName" : "Frodo",
      "lastName" : "Baggins",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/people/0"
        },
        "person" : {
          "href" : "http://localhost:8080/people/0"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/search/findByLastName?name=Baggins"
    }
  }
}

Because you defined it to return List<Person> in the code, it returns all of the results. If you had defined it to return only Person, it would pick one of the Person objects to return. Since this can be unpredictable, you probably do not want to do that for queries that can return multiple entries.

You can also issue PUT, PATCH, and DELETE REST calls to either replace, update, or delete existing records. The following example (shown with its output) shows a PUT call:

$ curl -X PUT -H "Content-Type:application/json" -d '{ "firstName": "Bilbo", "lastName": "Baggins" }' http://localhost:8080/people/0
$ curl http://localhost:8080/people/0
{
  "firstName" : "Bilbo",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/0"
    }
  }
}

The following example (shown with its output) shows a PATCH call:

$ curl -X PATCH -H "Content-Type:application/json" -d '{ "firstName": "Bilbo Jr." }' http://localhost:8080/people/0
$ curl http://localhost:8080/people/0
{
  "firstName" : "Bilbo Jr.",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/0"
    }
  }
}
Note
 PUT replaces an entire record. Fields that are not supplied are replaced with null. PATCH can be used to update a subset of items.

You can also delete records, as the following example (shown with its output) shows:

$ curl -X DELETE http://localhost:8080/people/0
$ curl http://localhost:8080/people
{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people{?page,size,sort}",
      "templated" : true
    },
    "search" : {
      "href" : "http://localhost:8080/people/search"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}

A convenient aspect of this hypermedia-driven interface is how you can discover all the RESTful endpoints by using curl (or whatever REST client you like). You need not exchange a formal contract or interface document with your customers.

Summary

Congratulations! You have just developed an application with a hypermedia-based RESTful front end and a Neo4j-based back end.