##### neo4j-server

- Introduction
- Getting Started (wiki)
- REST API
- JavaDocs
- Source Repository

##### Project Documentation

- Project Information
- Project Reports

## Neo4j REST API

The Neo4j REST API is designed with discoverability in mind, so that you can start with a `GET /` and from there discover URIs to do other stuff. Examples below uses URIs for examples; they are subject to change in the future, so for future-proofness discover URIs where possible, instead of relying on current layout. The default representation is json, both for responses and for data sent with `POST`/`PUT` requests.

Below follows a listing of ways to interact with the REST API. You can also see a (at runtime) generated description of the API be pointing your browser to the (exact URI may vary) http://localhost:7474/db/data/application.wadl

To interact with the JSON interface you must explicitly set request header Accept:application/json for those requests that responds with data. You should also set header Content-Type:application/json if your request sends data, for example when you're creating a relationship.

## Ways to interact

- Get root
- Create empty node
- Create node with properties
- Get node
- Set properties on node
- Get properties on node
- Remove properties from node
- Set property on node
- Get property on node
- Remove property from node
- Delete node
- Create relationship
- Set properties on relationship
- Get properties on relationship
- Remove properties from relationship
- Set property on relationship
- Get property on relationship
- Remove property from relationship
- Delete relationship
- Get relationships on node
- Get relationships types
- Listing node indexes
- Add indices with provided configuration parameters
- Listing relationship indexes
- Add to index
- Remove from index
- Remove from index without supplying value
- Remove from index with supplying neither key nor value
- Query index -- Exact
- Query index -- Advanced
- Traverse
- Finding a path between two nodes
- Finding paths between two nodes

### Get root

#### GET /

#### Example using curl

    curl -H Accept:application/json http://localhost:7474/db/data/

#### Response

##### 200

    {
      "node" : "http://localhost:7474/db/data/node",
      "node_index" : "http://localhost:7474/db/data/index/node",
      "relationship_index" : "http://localhost:7474/db/data/index/relationship",
      "reference_node" : "http://localhost:7474/db/data/node/0",
      "extensions_info" : "http://localhost:7474/db/data/ext",
      "extensions" : {
      }
    }

### Create empty node

#### POST /node

#### Example using curl

    curl -H Accept:application/json -X POST http://localhost:7474/db/data/node

#### Response

##### 201: OK, a node was created

Location: http://localhost:7474/db/data/node/123

### Create node with properties

#### POST /node

    { "name": "Thomas Anderson",
      "profession": "Hacker"
    }

#### Example using curl

    curl -H Accept:application/json -H Content-Type:application/json -X POST -d '{"name": "Thomas Anderson", "profession": "Hacker"}' http://localhost:7474/db/data/node

#### Response

##### 201: OK, a node was created

Location: http://localhost:7474/db/data/node/123

##### 400: Invalid data sent

### Get node

#### GET /node/123

#### Example using curl

    curl -H Accept:application/json http://localhost:7474/db/data/node/123

#### Response

##### 200: OK

    { "self": "http://localhost:7474/db/data/node/123",
      "data": { "name": "Thomas Anderson",
                "age": 29
      },
      "create_relationship": "http://localhost:7474/db/data/node/123/relationships",
      "all_relationships": "http://localhost:7474/db/data/node/123/relationships/all",
      "all_typed relationships": "http://localhost:7474/db/data/node/123/relationships/all/{-list|&|types}",
      "incoming_relationships": "http://localhost:7474/db/data/node/123/relationships/in",
      "incoming_typed relationships": "http://localhost:7474/db/data/node/123/relationships/in/{-list|&|types}",
      "outgoing_relationships": "http://localhost:7474/db/data/node/123/relationships/out",
      "outgoing_typed relationships": "http://localhost:7474/db/data/node/123/relationships/out/{-list|&|types}",
      "properties": "http://localhost:7474/db/data/node/123/properties",
      "property": "http://localhost:7474/db/data/node/123/property/{key}",
      "traverse": "http://localhost:7474/db/data/node/123/traverse/{returnType}"
    }

##### 404: Node not found

### Set properties on node

Replaces all properties on a node with the supplied set of properties.

#### PUT /node/123/properties

    { "name": "Thomas Anderson",
      "profession": "Hacker"
    }

#### Example using curl

    curl -H Content-Type:application/json -X PUT -d '{"name": "Thomas Anderson", "profession": "Hacker"}' http://localhost:7474/db/data/node/123/properties

#### Response

##### 204: OK, no content returned

##### 400: Invalid data sent

##### 404: Node node found

### Get properties on node

#### GET /node/123/properties

#### Example using curl

    curl -H Accept:application/json http://localhost:7474/db/data/node/123/properties

#### Response

##### 200: OK

    { "name": "Thomas Anderson",
      "profession": "Hacker"
    }

##### 204: OK, no properties found

##### 404: Node not found

### Remove properties from node

Removes all properties from a node.

#### DELETE /node/123/properties

#### Example using curl

    curl -X DELETE http://localhost:7474/db/data/node/123/properties

#### Response

##### 204: OK, no content returned

##### 404: Node not found

### Set property on node

#### PUT /node/123/properties/foo

    "the_value"

#### Example using curl

    curl -H Content-Type:application/json -X PUT -d '"the_value"' http://localhost:7474/db/data/node/123/properties/foo

#### Response

##### 204: OK, no content returned

##### 400: Invalid data sent

### Get property on node

#### GET /node/123/properties/foo

#### Example using curl

    curl -H Accept:application/json http://localhost:7474/db/data/node/123/properties/foo

#### Response

##### 200: OK

    "the_value"

##### 404: Node or property not found

### Remove property from node

#### DELETE /node/123/properties/foo

#### Example using curl

    curl -X DELETE http://localhost:7474/db/data/node/123/properties/foo

#### Response

##### 204: OK, no content returned

##### 404: Node or property not found

### Delete node

#### DELETE /node/123

#### Example using curl

    curl -X DELETE http://localhost:7474/db/data/node/123

#### Response

##### 204: OK, no content returned

##### 404: Node not found

##### 409: Node could not be deleted (still has relationships?)

### Create relationship

#### POST /node/123/relationships

    { "to": "http://localhost:7474/db/data/node/152",
      "data": { "date", 1270559208258 },
      "type": "KNOWS"
    }

#### Example using curl

    curl -H Accept:application/json -H Content-Type:application/json -X POST -d '{"to": "http://localhost:7474/db/data/node/152", "data": {"date": 1270559208258}, "type": "KNOWS"}' http://localhost:7474/db/data/node/123/relationships

#### Response

##### 201: OK, a relationship was created

Location: http://localhost:7474/db/data/relationship/456

##### 400: Invalid data sent

##### 404: "to" node, or the node specified by the URI not found

### Set properties on relationship

Replaces all properties on a relationship with the supplied set of properties.

#### PUT /relationship/456/properties

    { "date": 1270559208258 }

#### Example using curl

    curl -H Content-Type:application/json -X PUT -d '{"date": 1270559208258}' http://localhost:7474/db/data/relationship/456/properties

#### Response

##### 204: OK, no content returned

##### 400: Invalid data sent

##### 404: Relationship node found

### Get properties on relationship

#### GET /relationship/456/properties

#### Example using curl

    curl -H Accept:application/json http://localhost:7474/db/data/relationship/456/properties

#### Response

##### 200: OK

    { "date": 1270559208258 }

##### 204: OK, no properties found

##### 404: Relationship not found

### Remove properties from relationship

Removes all properties from a relationship.

#### DELETE /relationship/456/properties

#### Example using curl

    curl -X DELETE http://localhost:7474/db/data/relationship/456/properties

#### Response

##### 204: OK, no content returned

##### 404: Relationship not found

### Set property on relationship

#### PUT /relationship/456/properties/foo

    "the_value"

#### Example using curl

    curl -H Content-Type:application/json -X PUT -d '"the_value"' http://localhost:7474/db/data/relationship/456/properties/foo

#### Response

##### 204: OK, no content returned

##### 400: Invalid data sent

##### 404: Relationship not found

### Get property on relationship

#### GET /relationship/456/properties/foo

#### Example using curl

    curl -H Accept:application/json http://localhost:7474/db/data/relationship/456/properties/foo

#### Response

##### 200: OK

    "the_value"

##### 404: Relationship or property not found

### Remove property from relationship

#### DELETE /relationship/456/properties/foo

#### Example using curl

    curl -X DELETE http://localhost:7474/db/data/relationship/456/properties/foo

#### Response

##### 204: OK, no content returned

##### 404: Relationship or property not found

### Delete relationship

#### DELETE /relationship/456

#### Example using curl

    curl -X DELETE http://localhost:7474/db/data/relationship/456

#### Response

##### 204: OK, no content returned

##### 404: Relationship not found

### Get relationships on node

#### GET /node/123/relationships/{dir}/{-list|&|types}

Where dir is one of all,in,out and types is an ampersand-separated list of types. Some examples:

- GET /node/123/relationships/out/KNOWS&LOVES -- outgoing relationships of types KNOWS and LOVES
- GET /node/123/relationships/all/KNOWS -- relationships (both outgoing and incoming) of type LOVES
- GET /node/123/relationships/in -- incoming relationships

#### Example using curl

    curl -H Accept:application/json http://localhost:7474/db/data/node/123/relationships/out/KNOWS\&LOVES

Note: The ''&'' must be esaped in bash-like terminals (as included in the example, ''\'')

#### Response

##### 200: OK

    [
      { "self": "http://localhost:7474/db/data/relationship/56",
        "start": "http://localhost:7474/db/data/node/123",
        "end": "http://localhost:7474/db/data/node/93",
        "type": "KNOWS",
        "properties": "http://localhost:7474/db/data/relationship/56/properties",
        "property": "http://localhost:7474/db/data/relationship/56/properties/{key}",
        "data": { "date", 1270559208258 }
      },
      { "self": "http://localhost:7474/db/data/relationship/834",
        "start": "http://localhost:7474/db/data/node/32",
        "end": "http://localhost:7474/db/data/node/123",
        "type": "LOVES",
        "properties": "http://localhost:7474/db/data/relationship/834/properties",
        "property": "http://localhost:7474/db/data/relationship/834/properties/{key}",
        "data": { "date", 1270559203821 }
      }
    ]

##### 404: Node not found

### Get relationships types

#### GET /relationship/types

#### Example using curl

    curl -H Accept:application/json http://localhost:7474/db/data/relationship/types

#### Response

##### 200: OK

    [
      "KNOWS",
      "LOVES"
    ]

### Listing node indexes

#### GET /index/node

#### Example using curl

    curl -H Accept:application/json http://localhost:7474/db/data/index/node

#### Response

##### 200: OK

    {
      "my_nodes" : {
        "template" : "http://localhost:7474/db/data/index/node/my_nodes/{key}/{value}",
        "provider" : "lucene",
        "type" : "exact"
      }
    }

### Add indices with provided configuration parameters

#### POST /index/node

#### Example using curl

    curl-X POST -H Accept:application/json -HContent-Type:application/json -d '{"name":"fulltext", "config":{"type":"fulltext","provider":"lucene"}}' http://localhost:7474/db/data/index/node

#### Response

##### 200: OK

    {
      "template" : "http://localhost:7474/db/data/index/node/testing-fulltext/{key}/{value}",
      "provider" : "lucene",
      "type" : "fulltext"
    }

### Listing relationship indexes

#### GET /index/relationship

#### Example using curl

    curl -H Accept:application/json http://localhost:7474/db/data/index/relationship

#### Response

##### 200: OK

    {
      "my_relationships" : {
        "template" : "http://localhost:7474/db/data/index/relationship/my_relationships/{key}/{value}",
        "provider" : "lucene",
        "type" : "exact"
      }
    }

### Add to index

#### POST /index/node/my_nodes/the_key/the_value

    "http://localhost:7474/db/data/node/123"

#### Example using curl

    curl -HContent-Type:application/json -X POST -d '"http://localhost:7474/db/data/node/123"' http://localhost:7474/db/data/index/node/my_nodes/the_key/the_value%20with%20space

#### Response

##### 201: OK, indexed the node with key/value

Location: http://localhost:7474/db/data/index/node/my_nodes/the_key/the_value%20with%20space/123

#### POST /index/relationship/my_relationships/the_key/the_value

    "http://localhost:7474/db/data/relationship/456"

#### Example using curl

    curl -HContent-Type:application/json -X POST -d '"http://localhost:7474/db/data/relationship/123"' http://localhost:7474/db/data/index/relationship/my_relationships/the_key/the_value

#### Response

##### 201: OK, indexed the node with key/value

Location: http://localhost:7474/db/data/index/relationships/my_relationships/the_key/the_value/456

### Remove from index

#### DELETE /index/node/my_nodes/the_key/the_value/123

Such a URI is gotten from either a query to an index, where they will be included in the node/relationship returned representation. They are also returned (as Location in response header) when adding to an index.

Similarly for relationship indexes.

#### Example using curl

    curl -X DELETE http://localhost:7474/db/data/index/node/my_nodes/the_key/the_value/123

#### Response

##### 204: OK, no content returned

##### 404: Index entry not found

### Remove from index without supplying value

#### DELETE /index/node/my_nodes/the_key/123

Will remove all indexing for node 123 and the specified key irregardless of value. Similarly for relationship indexes.

#### Example using curl

    curl -X DELETE http://localhost:7474/db/data/index/node/my_nodes/the_key/123

#### Response

##### 204: OK, no content returned

### Remove from index with supplying neither key nor value

#### DELETE /index/node/my_nodes/123

Will remove all indexing for node 123 irregardless of key and value. Similarly for relationship indexes.

#### Example using curl

    curl -X DELETE http://localhost:7474/db/data/index/node/my_nodes/123

#### Response

##### 204: OK, no content returned

### Query index -- Exact

There are two ways to query an index - using the get method, or the more advanced query method. Use the first for exact matches, and the second for advanced index querying.

This is the simple, exact matching get operation.

#### GET /index/node/my_nodes/the_key/the_value

#### GET /index/relationship/my_rels/the_key/the_value

#### Example using curl

    curl -H Accept:application/json http://localhost:7474/db/data/index/node/my_nodes/the_key/the_value%20with%20space
    curl -H Accept:application/json http://localhost:7474/db/data/index/relationship/my_rels/the_key/the_value%20with%20space

#### Response

##### 200: OK

    [
      { "self": "http://localhost:7474/db/data/node/5",
        "data": { "name": "Thomas Anderson" },
        ...
        "indexed": "http://localhost:7474/db/data/index/node/the_key/the_value/5"
      },
      { "self": "http://localhost:7474/db/data/node/325",
        "data": { "name": "Agent Smith" },
        ...
        "indexed": "http://localhost:7474/db/data/index/node/the_key/the_value%20with%20space/325"
      }
    ]

The response is an ordered list of node or relationship representations, with one new property added: indexed. This property can be used to remove the indexed entity at a later point.

### Query index -- Advanced

This is the advanced query operation for an index.

#### GET /index/node/my_nodes/the_key?query=the_value

#### GET /index/relationship/my_rels/the_key?query=the_value

#### Example using curl

    curl -H Accept:application/json http://localhost:7474/db/data/index/node/my_nodes/the_key?query=the_value%20with%20space
    curl -H Accept:application/json http://localhost:7474/db/data/index/relationship/my_rels/the_key?query=the_value%20with%20space

The response is an ordered list of node/relationship representations.

### Traverse

#### POST /node/123/traverse/{returnType}

Where returnType is one if node, relationship, path, fullpath and specifies which kind of objects to return in the response.

The position object in the body of the prune evaluator is a org.neo4j.graphdb.Path object representing the path from the start node to the current traversal position.

    {
      "order": "depth first",
      "uniqueness": "node path",
      "relationships": [
        { "type": "KNOWS", "direction": "out" },
        { "type": "LOVES" }
      ],
      "prune evaluator": {
        "language": "javascript",
        "body": "position.endNode().getProperty('date')>1234567;"
      },
      "return filter": {
        "language": "builtin",
        "name": "all"
      },
      "max depth": 2
    }

"max depth" is a short-hand way of specifying a prune evaluator which prunes after a certain depth. If not specified a max depth of 1 is used and if a "prune evaluator" is specified instead of a max depth, no max depth limit is set.

Builtin prune evaluators: none

Builtin return filters: all, all but start node

#### Example using curl

    curl -H Accept:application/json -H Content-Type:application/json -X POST -d '{"order":"depth first"}' http://localhost:7474/db/data/node/123/traverse/node

#### Response

##### 200: OK

If returnType=node:

    [
      { "self": "http://localhost:7474/db/data/node/64",
        "data": { "name": "Thomas Anderson" },
        ...
      },
      { "self": "http://localhost:7474/db/data/node/635",
        "data": { "name": "Agent Smith" },
        ...
      }
    ]

If returnType=relationship:

    [
      { "self": "http://localhost:7474/db/data/relationship/48",
        "data": { "date", 1270559208258 },
        ...
      },
      { "self": "http://localhost:7474/db/data/relationship/75",
        "data": { "date", 1270559209483 },
        ...
      }
    ]

If returnType=path:

    [
      { "nodes": [
          "http://localhost:7474/db/data/node/2",
          "http://localhost:7474/db/data/node/351",
          "http://localhost:7474/db/data/node/64"
        ],
        "relationships": [
          "http://localhost:7474/db/data/relationship/5",
          "http://localhost:7474/db/data/relationship/48"
        ],
        "start": "http://localhost:7474/db/data/node/2",
        "end": "http://localhost:7474/db/data/node/64",
        "length": 3
      },
      { "nodes": [
          "http://localhost:7474/db/data/node/2",
          "http://localhost:7474/db/data/node/351",
          "http://localhost:7474/db/data/node/635"
        ],
        "relationships": [
          "http://localhost:7474/db/data/relationship/5",
          "http://localhost:7474/db/data/relationship/75"
        ],
        "start": "http://localhost:7474/db/data/node/2",
        "end": "http://localhost:7474/db/data/node/635",
        "length": 3
      },
    ]

If returnType=fullpath:

    [
      { "nodes": [
      { "self": "http://localhost:7474/db/data/node/64",
        "data": { "name": "Thomas Anderson" },
        ...
      },
      { "self": "http://localhost:7474/db/data/node/635",
        "data": { "name": "Agent Smith" },
        ...
      }],
        "relationships": [
      { "self": "http://localhost:7474/db/data/relationship/48",
        "data": { "date", 1270559208258 },
        ...
      },
      { "self": "http://localhost:7474/db/data/relationship/75",
        "data": { "date", 1270559209483 },
        ...
      }],
        "start":
      { "self": "http://localhost:7474/db/data/node/64",
        "data": { "name": "Thomas Anderson" },
        ...
      },
        "end":
            { "self": "http://localhost:7474/db/data/node/635",
                "data": { "name": "Agent Smith" },
                ...
              },
        "length": 3
      },
      { "nodes": [
    ....
        "length": 3
      }
    ]

##### 404: Node not found

### Finding a path between two nodes

#### POST /node/123/path

    { "to": "http://localhost:7474/db/data/node/456",
      "relationships": {"type": "KNOWS", "direction": "out"},
      "max depth": 3,
      "algorithm", "shortestPath"
    }

The "algorithm" parameter should match the name of the corresponding method in GraphAlgoFactory. Currently supported algos are: shortestPath, allPaths, allSimplePaths and dijkstra.

#### Example using curl

    curl -H Accept:application/json -H Content-Type:application/json -X POST http://localhost:7474/db/data/node/123/path -d '{"to":"http://localhost:7474/db/data/node/456","relationships":{"type":"KNOWS"},"algorithm":"shortestPath","max depth":10}'
    curl -H Accept:application/json -H Content-Type:application/json -X POST http://localhost:7474/db/data/node/123/path -d '{"to":"http://localhost:7474/db/data/node/456","relationships":{"type":"KNOWS"},"algorithm":"dijkstra","cost property":"cost","default cost":1}'

#### Response

##### 200

    { "start" : "http://localhost:7474/db/data/node/123",
      "nodes" : [ "http://localhost:7474/db/data/node/123", "http://localhost:7474/db/data/node/341", "http://localhost:7474/db/data/node/456" ],
      "length" : 2,
      "relationships" : [ "http://localhost:7474/db/data/relationship/564", "http://localhost:7474/db/data/relationship/32" ],
      "end" : "http://localhost:7474/db/data/node/456"
    }

Results from "dijkstra" algorithm will also have "weight".

##### 404: No path found using current algorithm and parameters

### Finding paths between two nodes

#### POST /node/123/paths

    { "to": "http://localhost:7474/db/data/node/456",
      "relationships": {"type": "KNOWS", "direction": "out"},
      "max depth": 3,
      "algorithm", "shortestPath"
    }

The "algorithm" parameter should match the name of the corresponding method in GraphAlgoFactory. Currently supported algos are: shortestPath, allPaths, allSimplePaths and dijkstra. More will be supported later on.

#### Example using curl

    curl -H Accept:application/json -H Content-Type:application/json -X POST http://localhost:7474/db/data/node/123/paths -d '{"to":"http://localhost:7474/db/data/node/456","relationships":{"type":"KNOWS"},"algorithm":"shortestPath","max depth":10}'
    curl -H Accept:application/json -H Content-Type:application/json -X POST http://localhost:7474/db/data/node/123/paths -d '{"to":"http://localhost:7474/db/data/node/456","relationships":{"type":"KNOWS"},"algorithm":"dijkstra","cost property":"cost","default cost":1}'

#### Response

##### 200

    [ {
      "start" : "http://localhost:7474/db/data/node/123",
      "nodes" : [ "http://localhost:7474/db/data/node/123", "http://localhost:7474/db/data/node/341", "http://localhost:7474/db/data/node/456" ],
      "length" : 2,
      "relationships" : [ "http://localhost:7474/db/data/relationship/564", "http://localhost:7474/db/data/relationship/32" ],
      "end" : "http://localhost:7474/db/data/node/456"
    }, {
      "start" : "http://localhost:7474/db/data/node/123",
      "nodes" : [ "http://localhost:7474/db/data/node/123", "http://localhost:7474/db/data/node/41", "http://localhost:7474/db/data/node/456" ],
      "length" : 2,
      "relationships" : [ "http://localhost:7474/db/data/relationship/437", "http://localhost:7474/db/data/relationship/97" ],
      "end" : "http://localhost:7474/db/data/node/456"
    } ]

Results from "dijkstra" algorithm will also have "weight".

##### 204: No path found using current algorithm and parameters

## See also

- Getting started with REST on the Neo4j wiki