4.4 Neo4j REST API

文档摘要

4.4 Neo4j REST API 4.4 Neo4j REST API 详解：代码实践与应用解析 4.4.1 引言在 Neo4j 的开发与应用领域中，REST API 扮演着至关重要的角色。作为一种轻量级、灵活且广泛支持的接口，Neo4j REST API 允许开发者通过 HTTP 协议与 Neo4j 图数据库进行交互，执行各种操作，例如数据查询、创建、更新和删除。它为各种编程语言和客户端应用提供了便捷的访问 Neo4j 的途径，极大地扩展了 Neo4j 的应用场景。 4.4.2 REST API 概述与优势 REST (Representational State Transfer) 是一种架构风格，用于构建分布式系统，尤其适用于 Web 服务。

4.4 Neo4j REST API

4.4 Neo4j REST API 详解：代码实践与应用解析

4.4.1 引言

在 Neo4j 的开发与应用领域中，REST API 扮演着至关重要的角色。作为一种轻量级、灵活且广泛支持的接口，Neo4j REST API 允许开发者通过 HTTP 协议与 Neo4j 图数据库进行交互，执行各种操作，例如数据查询、创建、更新和删除。它为各种编程语言和客户端应用提供了便捷的访问 Neo4j 的途径，极大地扩展了 Neo4j 的应用场景。

4.4.2 REST API 概述与优势

REST (Representational State Transfer) 是一种架构风格，用于构建分布式系统，尤其适用于 Web 服务。RESTful API 设计的核心原则包括：

客户端-服务器架构 (Client-Server): 客户端和服务器端分离，通过统一接口进行交互，各自独立演化。
无状态性 (Stateless): 服务器不保存客户端的状态，每次请求都必须包含所有必要的信息，保证请求的独立性和可伸缩性。
可缓存性 (Cacheable): 响应数据可以被缓存，提高性能和效率。
分层系统 (Layered System): 系统可以由多层组件组成，客户端无需了解中间层细节。
按需代码 (Code-On-Demand) (可选): 服务器可以向客户端传输可执行代码，扩展客户端功能 (Neo4j REST API 中不常用)。
统一接口 (Uniform Interface): 这是 REST 最重要的原则，包含以下几个方面：
- 资源识别 (Resource Identification): 每个资源都通过 URI 唯一标识。
- 资源操作 (Resource Manipulation through Representations): 客户端通过表述 (例如 JSON) 来操作资源，服务器返回资源的表述。
- 自描述消息 (Self-descriptive Messages): 消息本身包含足够的信息，例如 Content-Type 头部，让接收者能够理解如何处理消息。
- 超媒体作为应用状态引擎 (HATEOAS - Hypermedia as the Engine of Application State) (可选): API 响应中包含指向相关资源的链接，引导客户端操作 (Neo4j REST API 部分支持)。

Neo4j REST API 的优势：

跨平台与语言无关性: 基于 HTTP 协议，几乎所有编程语言和平台都能够方便地与其交互。
易于使用和理解: REST 架构简洁明了，易于学习和使用，降低了开发门槛。
轻量级: 基于 HTTP 和 JSON，传输数据量小，效率高。
松耦合: 客户端和服务器端解耦，方便独立开发和维护。
广泛的应用场景: 适用于 Web 应用、移动应用、集成系统等多种场景。

4.4.3 Neo4j REST API 架构与核心概念

Neo4j REST API 基于 HTTP 协议，通过一系列预定义的 URL 路径 (endpoints) 来暴露图数据库的功能。客户端通过发送 HTTP 请求 (例如 GET, POST, PUT, DELETE) 到这些 endpoints，并携带必要的参数和数据 (通常以 JSON 格式)，与 Neo4j 服务器进行交互。

核心概念：

数据库实例 (Database Instance): Neo4j 服务器可以管理多个数据库实例。REST API 通常针对默认数据库 neo4j 进行操作，也可以通过 URL 指定其他数据库实例。
事务 (Transaction): Neo4j REST API 的操作通常在事务上下文中进行。事务保证了操作的原子性、一致性、隔离性和持久性 (ACID)。
节点 (Node): 图数据库的基本单元，代表实体或概念。节点可以拥有属性 (properties) 和标签 (labels)。
关系 (Relationship): 节点之间的连接，代表实体之间的关联。关系有类型 (type) 和方向 (direction)，也可以拥有属性。
Cypher 查询语言: Neo4j 的查询语言，用于描述图模式和操作。REST API 允许客户端通过 Cypher 查询来检索和修改图数据。
JSON (JavaScript Object Notation): Neo4j REST API 主要使用 JSON 格式来传输数据，包括请求体和响应体。

REST API 架构图 (mermaid graph TD):

架构说明:

客户端应用 (Client Application): 例如 Web 应用、移动应用或其他需要访问 Neo4j 的系统。
Neo4j REST API Endpoint: Neo4j 服务器提供的 REST API 接口，监听 HTTP 请求。
Neo4j Server Instance: 运行 Neo4j 数据库服务的实例。
Cypher Execution Engine: 负责解析和执行 Cypher 查询的组件。
Database: 存储图数据的 Neo4j 数据库。

客户端应用通过 HTTP 请求与 REST API Endpoint 交互。Endpoint 接收请求后，会调用 Cypher Execution Engine 执行 Cypher 查询或进行数据操作，然后与 Database 交互读取或写入数据。最终，Neo4j Server 将处理结果封装成 HTTP 响应 (JSON 格式) 返回给客户端。

4.4.4 Neo4j REST API 关键操作与代码实践

本节将详细介绍 Neo4j REST API 的关键操作，并提供代码实践示例，包括使用 curl 命令行工具和 Python requests 库。

4.4.4.1 环境准备

在开始之前，请确保已安装并运行 Neo4j 版本。默认情况下，Neo4j REST API 监听在 http://localhost:7474。您可以使用 Neo4j Browser 或其他工具连接到 Neo4j 服务器，并确保服务正常运行。

4.4.4.2 基本认证

Neo4j REST API 默认需要基本认证。您需要提供用户名和密码才能访问 API。默认的用户名和密码通常是 neo4j/neo4j。在代码示例中，我们将使用基本认证。

4.4.4.3 创建节点 (Create Node)

使用 POST 请求发送到 /db/neo4j/tx/commit endpoint，并使用 Cypher 语句创建节点。

curl 示例:


curl -X POST \
     -H "Content-Type: application/json" \
     -H "Accept: application/json;charset=UTF-8" \
     -u neo4j:neo4j \
     -d '{
       "statements" : [ {
         "statement" : "CREATE (n:Person {name: $name, age: $age}) RETURN n",
         "parameters" : {
           "name" : "Alice",
           "age" : 30
         }
       } ]
     }' \
     http://localhost:7474/db/neo4j/tx/commit

Python requests 示例:


import requests
import json
url = "http://localhost:7474/db/neo4j/tx/commit"
headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json;charset=UTF-8'
}
auth = ('neo4j', 'neo4j')
data = {
    "statements": [{
        "statement": "CREATE (n:Person {name: $name, age: $age}) RETURN n",
        "parameters": {
            "name": "Bob",
            "age": 25
        }
    }]
}
response = requests.post(url, headers=headers, auth=auth, data=json.dumps(data))
if response.status_code == 200:
    print("Node created successfully!")
    print(response.json())
else:
    print(f"Error creating node. Status code: {response.status_code}")
    print(response.text)

代码解析:

curl -X POST 和 requests.post(): 使用 HTTP POST 方法发送请求。
-H "Content-Type: application/json" 和 headers = {'Content-Type': 'application/json'}: 指定请求体内容类型为 JSON。
-H "Accept: application/json;charset=UTF-8" 和 headers = {'Accept': 'application/json;charset=UTF-8'}: 指定期望接收的响应内容类型为 JSON。
-u neo4j:neo4j 和 auth = ('neo4j', 'neo4j'): 提供基本认证的用户名和密码。
-d '{...}' 和 data = {...}: 请求体数据，包含 statements 数组，每个元素是一个 Cypher 语句及其参数。
- statement: Cypher 语句 CREATE (n:Person {name: $name, age: $age}) RETURN n 用于创建带有标签 Person 和属性 name 和 age 的节点，并返回创建的节点 n。
- parameters: Cypher 语句中的参数，例如 $name 和 $age，其值分别在 parameters 字典中指定。
http://localhost:7474/db/neo4j/tx/commit: Neo4j 事务提交 endpoint，所有数据库修改操作都需要提交到此 endpoint。
response.status_code: HTTP 响应状态码，200 表示成功。
response.json(): 将 JSON 响应体解析为 Python 字典。

响应示例 (JSON):


{
  "results" : [ {
    "columns" : [ "n" ],
    "data" : [ {
      "row" : [ {
        "age" : 30,
        "name" : "Alice"
      } ],
      "meta" : [ {
        "id" : 0,
        "type" : "node",
        "deleted" : false
      } ]
    } ]
  } ],
  "errors" : [ ]
}

响应体包含 results 数组，其中包含 Cypher 语句的执行结果。data 数组中的 row 包含返回的节点属性，meta 包含节点的元数据，例如 id 和 type。errors 数组为空表示没有错误发生。

4.4.4.4 创建关系 (Create Relationship)

使用 POST 请求发送到 /db/neo4j/tx/commit endpoint，并使用 Cypher 语句创建关系。

curl 示例:


curl -X POST \
     -H "Content-Type: application/json" \
     -H "Accept: application/json;charset=UTF-8" \
     -u neo4j:neo4j \
     -d '{
       "statements" : [ {
         "statement" : "MATCH (a:Person {name: $name1}), (b:Person {name: $name2}) CREATE (a)-[r:KNOWS {since: $since}]->(b) RETURN r",
         "parameters" : {
           "name1" : "Alice",
           "name2" : "Bob",
           "since" : 2020
         }
       } ]
     }' \
     http://localhost:7474/db/neo4j/tx/commit

Python requests 示例:


import requests
import json
url = "http://localhost:7474/db/neo4j/tx/commit"
headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json;charset=UTF-8'
}
auth = ('neo4j', 'neo4j')
data = {
    "statements": [{
        "statement": "MATCH (a:Person {name: $name1}), (b:Person {name: $name2}) CREATE (a)-[r:KNOWS {since: $since}]->(b) RETURN r",
        "parameters": {
            "name1": "Alice",
            "name2": "Bob",
            "since": 2021
        }
    }]
}
response = requests.post(url, headers=headers, auth=auth, data=json.dumps(data))
if response.status_code == 200:
    print("Relationship created successfully!")
    print(response.json())
else:
    print(f"Error creating relationship. Status code: {response.status_code}")
    print(response.text)

代码解析:

statement: Cypher 语句 MATCH (a:Person {name: $name1}), (b:Person {name: $name2}) CREATE (a)-[r:KNOWS {since: $since}]->(b) RETURN r 用于：
- MATCH (a:Person {name: $name1}), (b:Person {name: $name2}): 匹配两个节点，标签为 Person，属性 name 分别为 $name1 和 $name2。
- CREATE (a)-[r:KNOWS {since: $since}]->(b): 在匹配到的节点 a 和 b 之间创建关系 r，类型为 KNOWS，属性 since 为 $since。
- RETURN r: 返回创建的关系 r。
parameters: Cypher 语句中的参数，用于指定节点名称和关系属性。

4.4.4.5 查询数据 (Query Data)

使用 POST 请求发送到 /db/neo4j/tx/commit endpoint，并使用 Cypher 语句查询数据。

curl 示例:


curl -X POST \
     -H "Content-Type: application/json" \
     -H "Accept: application/json;charset=UTF-8" \
     -u neo4j:neo4j \
     -d '{
       "statements" : [ {
         "statement" : "MATCH (n:Person) WHERE n.age > $age RETURN n.name, n.age",
         "parameters" : {
           "age" : 28
         }
       } ]
     }' \
     http://localhost:7474/db/neo4j/tx/commit

Python requests 示例:


import requests
import json
url = "http://localhost:7474/db/neo4j/tx/commit"
headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json;charset=UTF-8'
}
auth = ('neo4j', 'neo4j')
data = {
    "statements": [{
        "statement": "MATCH (n:Person) WHERE n.age > $age RETURN n.name, n.age",
        "parameters": {
            "age": 20
        }
    }]
}
response = requests.post(url, headers=headers, auth=auth, data=json.dumps(data))
if response.status_code == 200:
    print("Query executed successfully!")
    print(response.json())
else:
    print(f"Error executing query. Status code: {response.status_code}")
    print(response.text)

代码解析:

statement: Cypher 语句 MATCH (n:Person) WHERE n.age > $age RETURN n.name, n.age 用于：
- MATCH (n:Person): 匹配所有标签为 Person 的节点 n。
- WHERE n.age > $age: 过滤节点，只保留属性 age 大于 $age 的节点。
- RETURN n.name, n.age: 返回符合条件的节点的 name 和 age 属性。
parameters: Cypher 语句中的参数，用于指定年龄阈值。

响应示例 (JSON):


{
  "results" : [ {
    "columns" : [ "n.name", "n.age" ],
    "data" : [ {
      "row" : [ "Alice", 30 ],
      "meta" : [ null, null ]
    }, {
      "row" : [ "Bob", 25 ],
      "meta" : [ null, null ]
    } ]
  } ],
  "errors" : [ ]
}

响应体包含查询结果，columns 数组指定返回的列名，data 数组中的 row 包含每一行的数据，meta 数组为 null 表示没有元数据返回。

4.4.4.6 更新节点属性 (Update Node Properties)

使用 POST 请求发送到 /db/neo4j/tx/commit endpoint，并使用 Cypher 语句更新节点属性。

curl 示例:


curl -X POST \
     -H "Content-Type: application/json" \
     -H "Accept: application/json;charset=UTF-8" \
     -u neo4j:neo4j \
     -d '{
       "statements" : [ {
         "statement" : "MATCH (n:Person {name: $name}) SET n.age = $newAge RETURN n",
         "parameters" : {
           "name" : "Alice",
           "newAge" : 32
         }
       } ]
     }' \
     http://localhost:7474/db/neo4j/tx/commit

Python requests 示例:


import requests
import json
url = "http://localhost:7474/db/neo4j/tx/commit"
headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json;charset=UTF-8'
}
auth = ('neo4j', 'neo4j')
data = {
    "statements": [{
        "statement": "MATCH (n:Person {name: $name}) SET n.age = $newAge RETURN n",
        "parameters": {
            "name": "Bob",
            "newAge": 26
        }
    }]
}
response = requests.post(url, headers=headers, auth=auth, data=json.dumps(data))
if response.status_code == 200:
    print("Node properties updated successfully!")
    print(response.json())
else:
    print(f"Error updating node properties. Status code: {response.status_code}")
    print(response.text)

代码解析:

statement: Cypher 语句 MATCH (n:Person {name: $name}) SET n.age = $newAge RETURN n 用于：
- MATCH (n:Person {name: $name}): 匹配标签为 Person 且属性 name 为 $name 的节点 n。
- SET n.age = $newAge: 设置匹配到的节点的 age 属性为 $newAge。
- RETURN n: 返回更新后的节点 n。

4.4.4.7 删除节点 (Delete Node)

使用 POST 请求发送到 /db/neo4j/tx/commit endpoint，并使用 Cypher 语句删除节点。注意：删除节点会同时删除与之相关的关系。

curl 示例:


curl -X POST \
     -H "Content-Type: application/json" \
     -H "Accept: application/json;charset=UTF-8" \
     -u neo4j:neo4j \
     -d '{
       "statements" : [ {
         "statement" : "MATCH (n:Person {name: $name}) DELETE n",
         "parameters" : {
           "name" : "Alice"
         }
       } ]
     }' \
     http://localhost:7474/db/neo4j/tx/commit

Python requests 示例:


import requests
import json
url = "http://localhost:7474/db/neo4j/tx/commit"
headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json;charset=UTF-8'
}
auth = ('neo4j', 'neo4j')
data = {
    "statements": [{
        "statement": "MATCH (n:Person {name: $name}) DELETE n",
        "parameters": {
            "name": "Bob"
        }
    }]
}
response = requests.post(url, headers=headers, auth=auth, data=json.dumps(data))
if response.status_code == 200:
    print("Node deleted successfully!")
    print(response.json())
else:
    print(f"Error deleting node. Status code: {response.status_code}")
    print(response.text)

代码解析:

statement: Cypher 语句 MATCH (n:Person {name: $name}) DELETE n 用于：
- MATCH (n:Person {name: $name}): 匹配标签为 Person 且属性 name 为 $name 的节点 n。
- DELETE n: 删除匹配到的节点 n。

4.4.4.8 删除关系 (Delete Relationship)

使用 POST 请求发送到 /db/neo4j/tx/commit endpoint，并使用 Cypher 语句删除关系。

curl 示例:


curl -X POST \
     -H "Content-Type: application/json" \
     -H "Accept: application/json;charset=UTF-8" \
     -u neo4j:neo4j \
     -d '{
       "statements" : [ {
         "statement" : "MATCH (a:Person)-[r:KNOWS]->(b:Person) WHERE a.name = $name1 AND b.name = $name2 DELETE r",
         "parameters" : {
           "name1" : "Alice",
           "name2" : "Bob"
         }
       } ]
     }' \
     http://localhost:7474/db/neo4j/tx/commit

Python requests 示例:


import requests
import json
url = "http://localhost:7474/db/neo4j/tx/commit"
headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json;charset=UTF-8'
}
auth = ('neo4j', 'neo4j')
data = {
    "statements": [{
        "statement": "MATCH (a:Person)-[r:KNOWS]->(b:Person) WHERE a.name = $name1 AND b.name = $name2 DELETE r",
        "parameters": {
            "name1": "Alice",
            "name2": "Bob"
        }
    }]
}
response = requests.post(url, headers=headers, auth=auth, data=json.dumps(data))
if response.status_code == 200:
    print("Relationship deleted successfully!")
    print(response.json())
else:
    print(f"Error deleting relationship. Status code: {response.status_code}")
    print(response.text)

代码解析:

statement: Cypher 语句 MATCH (a:Person)-[r:KNOWS]->(b:Person) WHERE a.name = $name1 AND b.name = $name2 DELETE r 用于：
- MATCH (a:Person)-[r:KNOWS]->(b:Person): 匹配节点 a 和 b 之间类型为 KNOWS 的关系 r，节点 a 和 b 标签为 Person。
- WHERE a.name = $name1 AND b.name = $name2: 进一步过滤关系，限定节点 a 的 name 属性为 $name1，节点 b 的 name 属性为 $name2。
- DELETE r: 删除匹配到的关系 r。

4.4.5 事务管理 (Transaction Management)

Neo4j REST API 的所有修改操作 (创建、更新、删除) 都应该在事务中进行。使用 /db/neo4j/tx/commit endpoint 提交事务。

事务流程:

开始事务 (可选): 可以使用 /db/neo4j/tx endpoint 开始一个新的事务，并获取事务的 URI。后续请求可以发送到该 URI，直到事务提交或回滚。如果不显式开始事务，每次请求到 /db/neo4j/tx/commit 都会自动开始并提交一个事务。
执行操作: 发送请求到 /db/neo4j/tx/commit endpoint，包含需要执行的 Cypher 语句。
提交事务: 当所有操作都成功执行后，请求 /db/neo4j/tx/commit endpoint 完成事务提交。
回滚事务 (可选): 如果操作过程中发生错误，或者需要取消事务，可以请求 /db/neo4j/tx/{transactionId}/rollback endpoint 回滚事务。