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.
{ "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" : { } }
{ "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}" }
Replaces all properties on a node with the supplied set of properties.
Removes all properties from a node.
{ "to": "http://localhost:7474/db/data/node/152", "data": { "date", 1270559208258 }, "type": "KNOWS" }
Replaces all properties on a relationship with the supplied set of properties.
Removes all properties from a relationship.
Where dir is one of all,in,out and types is an ampersand-separated list of types. Some examples:
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, ''\'')
[ { "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 } } ]
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
"http://localhost:7474/db/data/relationship/456"
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.
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.
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
[ { "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.
This is the advanced query operation for an index.
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.
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
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
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 } ]
{ "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.
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}'
{ "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".
{ "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.
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}'
[ { "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".