coco/public-things-api

Public API for Things (public-things-api)

镜像概述和主要用途

提供存储在Neo4j图数据库中的事物（Things）的公共API。目前事物正迁移至新的https://github.com/Financial-Times/public-concepts-api%EF%BC%8C%E5%9B%A0%E6%AD%A4%E6%9C%ACAPI%E6%9C%80%E7%BB%88%E5%B0%86%E8%A2%AB%E5%BC%83%E7%94%A8%E3%80%82%E8%87%AA2018%E5%B9%B47%E6%9C%88%E8%B5%B7%EF%BC%8C%E5%AF%B9%E6%9C%AC%E6%9C%8D%E5%8A%A1%E7%9A%84%E8%AF%B7%E6%B1%82%E5%B0%86%E9%80%9A%E8%BF%87%E6%A6%82%E5%BF%B5API%E9%87%8D%E5%AE%9A%E5%90%91%EF%BC%8C%E7%84%B6%E5%90%8E%E8%BD%AC%E6%8D%A2%E4%BB%A5%E5%8C%B9%E9%85%8D%E7%8E%B0%E6%9C%89%E5%A5%91%E7%BA%A6%E5%B9%B6%E8%BF%94%E5%9B%9E%E3%80%82

核心功能和特性

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

使用场景和适用范围

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

详细使用方法和配置说明

环境变量配置

Docker部署示例

基本运行

bash
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=http://public-concepts-api:8080 \
  docker.xuanyuan.run/coco/public-things-api

自定义配置

bash
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=http://concepts-api.example.com \
  docker.xuanyuan.run/coco/public-things-api --env=production

服务端点

获取单个事物描述

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

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

响应示例：

json
{
  "id": "http://api.ft.com/things/a11fa00f-777d-484a-9ebc-fbf81b774fc0",
  "apiUrl": "http://api.ft.com/things/a11fa00f-777d-484a-9ebc-fbf81b774fc0",
  "prefLabel": "Solar Wars",
  "types": [
    "http://www.ft.com/ontology/core/Thing",
    "http://www.ft.com/ontology/concept/Concept",
    "http://www.ft.com/ontology/Topic"
  ],
  "directType": "http://www.ft.com/ontology/Topic",
  "aliases": [
    "Solar Wars"
  ]
}

获取带关系的事物描述

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

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

响应示例（包含关系）：

json
{
  "id": "http://api.ft.com/things/a11fa00f-777d-484a-9ebc-fbf81b774fc0",
  "apiUrl": "http://api.ft.com/things/a11fa00f-777d-484a-9ebc-fbf81b774fc0",
  "prefLabel": "Solar Wars",
  "types": [
    "http://www.ft.com/ontology/core/Thing",
    "http://www.ft.com/ontology/concept/Concept",
    "http://www.ft.com/ontology/Topic"
  ],
  "directType": "http://www.ft.com/ontology/Topic",
  "aliases": [
    "Solar Wars"
  ],
  "narrowerConcepts": [
    {
      "id": "http://api.ft.com/things/0ff1c1c9-970a-4f05-9f97-c5150f8f907e",
      "apiUrl": "http://api.ft.com/things/0ff1c1c9-970a-4f05-9f97-c5150f8f907e",
      "prefLabel": "Macroeconomics",
      "types": [
        "http://www.ft.com/ontology/core/Thing",
        "http://www.ft.com/ontology/concept/Concept",
        "http://www.ft.com/ontology/Topic"
      ],
      "directType": "http://www.ft.com/ontology/Topic",
      "predicate": "http://www.w3.org/2004/02/skos/core#narrower"
    }
  ],
  "broaderConcepts": [
    {
      "id": "http://api.ft.com/things/49181791-a1a9-4966-ac30-010846ec76d8",
      "apiUrl": "http://api.ft.com/things/49181791-a1a9-4966-ac30-010846ec76d8",
      "prefLabel": "Trade disputes",
      "types": [
        "http://www.ft.com/ontology/core/Thing",
        "http://www.ft.com/ontology/concept/Concept",
        "http://www.ft.com/ontology/Topic"
      ],
      "directType": "http://www.ft.com/ontology/Topic",
      "predicate": "http://www.w3.org/2004/02/skos/core#broader"
    }
  ],
  "relatedConcepts": [
    {
      "id": "http://api.ft.com/things/29e9fad1-14fc-480b-a89c-cd964750bd80",
      "apiUrl": "http://api.ft.com/things/29e9fad1-14fc-480b-a89c-cd964750bd80",
      "prefLabel": "Renewable Energy",
      "types": [
        "http://www.ft.com/ontology/core/Thing",
        "http://www.ft.com/ontology/concept/Concept",
        "http://www.ft.com/ontology/Topic"
      ],
      "directType": "http://www.ft.com/ontology/Topic",
      "predicate": "http://www.w3.org/2004/02/skos/core#related"
    }
  ]
}

批量获取多个事物描述

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

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

响应示例：

json
{
  "things": {
    "a11fa00f-777d-484a-9ebc-fbf81b774fc0": {
      "id": "http://api.ft.com/things/a11fa00f-777d-484a-9ebc-fbf81b774fc0",
      "apiUrl": "http://api.ft.com/things/a11fa00f-777d-484a-9ebc-fbf81b774fc0",
      "prefLabel": "Solar Wars",
      "types": [
        "http://www.ft.com/ontology/core/Thing",
        "http://www.ft.com/ontology/concept/Concept",
        "http://www.ft.com/ontology/Topic"
      ],
      "directType": "http://www.ft.com/ontology/Topic",
      "aliases": [
        "Solar Wars"
      ]
    },
    "non-canonical-uuid": {
      "id": "http://api.ft.com/things/canonical-uuid",
      "apiUrl": "http://api.ft.com/things/canonical-uuid",
      "prefLabel": "Resolved Thing",
      "types": [
        "http://www.ft.com/ontology/core/Thing",
        "http://www.ft.com/ontology/concept/Concept"
      ],
      "directType": "http://www.ft.com/ontology/concept/Concept",
      "aliases": []
    }
  }
}

健康检查端点

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

日志

• 使用https://github.com/sirupsen/logrus%E8%AE%B0%E5%BD%95%E6%97%A5%E5%BF%97%EF%BC%8C%E9%85%8D%E7%BD%AE%E5%9C%A8%60main.go%60%E4%B8%AD%E5%88%9D%E5%A7%8B%E5%8C%96
• 日志输出位置：
  • local环境：日志输出到控制台
  • 其他环境：日志输出到文件
• /__build-info和/__ping端点的请求不记录日志

安装（源码）

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

1. 安装依赖管理工具：

bash
curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh

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

bash
mkdir $GOPATH/src/github.com/Financial-Times/public-things-api
cd $GOPATH/src/github.com/Financial-Times
git clone https://github.com/Financial-Times/public-things-api.git
cd public-things-api && dep ensure -vendor-only

3. 构建：

bash
go build .

本地运行

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

bash
go test ./...
go install

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

bash
$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"）