Public API for Things (public-things-api)

镜像概述和主要用途

提供存储在Neo4j图数据库中的事物（Things）的公共API。目前事物正迁移至新的Public Concepts API，因此本API最终将被弃用。自2018年7月起，对本服务的请求将通过概念API重定向，然后转换以匹配现有契约并返回。

核心功能和特性

• 提供事物描述的读取接口，支持通过UUID获取单个事物信息
• 支持批量获取多个事物描述，自动处理非规范UUID并解析为规范UUID
• 可通过showRelationship查询参数获取事物间的关系（包括broader、broaderTransitive、narrower、related类型）
• 提供健康检查端点（/__gtg、/__health、/__build-info、/__ping）
• 支持缓存控制，可配置GET请求的缓存时长
• 基于环境变量配置，便于容器化部署

使用场景和适用范围

适用于需要读取Neo4j图数据库中存储的事物信息的应用，可获取事物的基本信息及其与其他概念的关系。注意：本API正处于迁移阶段，未来将被Public Concepts API替代，建议新应用直接使用Public Concepts API。

详细使用方法和配置说明

环境变量配置

Docker部署示例

基本运行

docker run -d -p 8080:8080 \
  -e APP_SYSTEM_CODE=public-things-api \
  -e APP_PORT=8080 \
  -e CACHE_DURATION=30s \
  -e LOG_LEVEL=info \
  -e CONCEPTS_API=[***] \
  coco/public-things-api

自定义配置

docker run -d -p 8081:8081 \
  -e APP_SYSTEM_CODE=my-things-api \
  -e APP_PORT=8081 \
  -e CACHE_DURATION=5m \
  -e LOG_LEVEL=debug \
  -e CONCEPTS_API=[***] \
  coco/public-things-api --env=production

服务端点

获取单个事物描述

通过UUID获取事物的基本信息：

curl http://localhost:8080/things/{concept-uuid} | jq

响应示例：

{
  "id": "[***]",
  "apiUrl": "[***]",
  "prefLabel": "Solar Wars",
  "types": [
    "[***]",
    "[***]",
    "[***]"
  ],
  "directType": "[***]",
  "aliases": [
    "Solar Wars"
  ]
}

获取带关系的事物描述

通过showRelationship参数获取事物与其他概念的关系，支持的值：broader（ broader关系）、broaderTransitive（broader传递关系）、narrower（narrower关系）、related（related关系）。

curl "http://localhost:8080/things/{concept-uuid}?showRelationship=broaderTransitive&showRelationship=related&showRelationship=narrower" | jq

响应示例（包含关系）：

{
  "id": "[***]",
  "apiUrl": "[***]",
  "prefLabel": "Solar Wars",
  "types": [
    "[***]",
    "[***]",
    "[***]"
  ],
  "directType": "[***]",
  "aliases": [
    "Solar Wars"
  ],
  "narrowerConcepts": [
    {
      "id": "[***]",
      "apiUrl": "[***]",
      "prefLabel": "Macroeconomics",
      "types": [
        "[***]",
        "[***]",
        "[***]"
      ],
      "directType": "[***]",
      "predicate": "[***]"
    }
  ],
  "broaderConcepts": [
    {
      "id": "[***]",
      "apiUrl": "[***]",
      "prefLabel": "Trade disputes",
      "types": [
        "[***]",
        "[***]",
        "[***]"
      ],
      "directType": "[***]",
      "predicate": "[***]"
    }
  ],
  "relatedConcepts": [
    {
      "id": "[***]",
      "apiUrl": "[***]",
      "prefLabel": "Renewable Energy",
      "types": [
        "[***]",
        "[***]",
        "[***]"
      ],
      "directType": "[***]",
      "predicate": "[***]"
    }
  ]
}

批量获取多个事物描述

通过多个uuid参数批量获取事物描述，支持自动解析非规范UUID：

curl "http://localhost:8080/things?uuid={canonical-uuid}&uuid={non-canonical-uuid}&uuid={another-uuid}" | jq

响应示例：

{
  "things": {
    "a11fa00f-777d-484a-9ebc-fbf81b774fc0": {
      "id": "[***]",
      "apiUrl": "[***]",
      "prefLabel": "Solar Wars",
      "types": [
        "[***]",
        "[***]",
        "[***]"
      ],
      "directType": "[***]",
      "aliases": [
        "Solar Wars"
      ]
    },
    "non-canonical-uuid": {
      "id": "[***]",
      "apiUrl": "[***]",
      "prefLabel": "Resolved Thing",
      "types": [
        "[***]",
        "[***]"
      ],
      "directType": "[***]",
      "aliases": []
    }
  }
}

健康检查端点

• /__gtg: 健康状态检查（返回200表示正常）
• /__health: 详细健康信息
• /__build-info: 应用构建信息
• /__ping: 心跳检查（返回"pong"）

日志

• 使用logrus记录日志，配置在main.go中初始化
• 日志输出位置：
  • local环境：日志输出到控制台
  • 其他环境：日志输出到文件
• /__build-info和/__ping端点的请求不记录日志

安装（源码）

如需从源码构建，执行以下步骤：

1. 安装依赖管理工具：

curl [***] | sh

2. 创建目录并克隆代码：

mkdir $GOPATH/src/github.com/Financial-Times/public-things-api
cd $GOPATH/src/github.com/Financial-Times
git clone [***]
cd public-things-api && dep ensure -vendor-only

3. 构建：

go build .

本地运行

1. 运行测试并安装二进制：

go test ./...
go install

2. 启动服务（使用--help查看参数）：

$GOPATH/bin/public-things-api --help

参数说明：

Options:
  --app-system-code        应用的系统代码（环境变量 $APP_SYSTEM_CODE）（默认 "public-things-api"）
  --port                   监听端口（环境变量 $APP_PORT）（默认 "8080"）
  --env                    应用运行环境（默认 "local"）
  --cache-duration         GET请求缓存时长（例如2h45m）（环境变量 $CACHE_DURATION）（默认 "30s"）
  --logLevel               日志级别（环境变量 $LOG_LEVEL）（默认 "info"）
  --publicConceptsApiURL   Public Concepts API端点URL（环境变量 $CONCEPTS_API）（默认 "http://localhost:8080"）