coco/draft-annotations-api

Draft Annotations API

概述

Draft Annotations API是一个微服务，提供对存储在PAC中的内容草稿注释的访问。

安装

下载源代码、依赖项和测试依赖项：

mkdir $GOPATH/src/github.com/Financial-Times/draft-annotations-api
cd $GOPATH/src/github.com/Financial-Times
git clone https://github.com/Financial-Times/draft-annotations-api.git
cd draft-annotations-api
GO111MODULE=on go build -mod=readonly

本地运行

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

GO111MODULE=on go test -mod=readonly ./...
go install

2. 运行二进制文件（使用help标志查看可用的可选参数）

$GOPATH/bin/draft-annotations-api [--help]

选项：
  --app-system-code="draft-annotations-api"                                        应用的系统代码 ($APP_SYSTEM_CODE)
  --app-name="draft-annotations-api"                                               应用名称 ($APP_NAME)
  --port="8080"                                                                    监听端口 ($APP_PORT)
  --annotations-rw-endpoint="http://localhost:8888"                                从数据库获取草稿注释的端点 ($ANNOTATIONS_RW_ENDPOINT)
  --upp-annotations-endpoint="http://test.api.ft.com/content/%v/annotations"       公共注释API端点 ($ANNOTATIONS_ENDPOINT)
  --internal-concordances-endpoint="http://test.api.ft.com/internalconcordances"   从UPP获取概念的端点 ($INTERNAL_CONCORDANCES_ENDPOINT)
  --internal-concordances-batch-size=30                                            查询UPP Internal Concordances API时使用的概念ID最大批大小 ($INTERNAL_CONCORDANCES_BATCH_SIZE)
  --upp-api-key=""                                                                 访问UPP的API密钥 ($UPP_APIKEY)
  --api-yml="./_ft/api.yml"                                                        API Swagger YML文件的位置 ($API_YML)
  --http-timeout="8s"                                                              请求超时前的等待时间 ($HTTP_TIMEOUT)
  --log-level="INFO"                                                               日志级别 ($LOG_LEVEL)

3. 测试

方法一：使用curl

bash
curl http://localhost:8080/draft/content/b7b871f6-8a89-11e4-8e24-00144feabdc0/annotations | json_pp

方法二：使用https://github.com/jkbrzt/httpie

bash
http GET http://localhost:8080/draft/content/b7b871f6-8a89-11e4-8e24-00144feabdc0/annotations

构建与部署

• 该应用作为Docker镜像构建，并通过Helm chart部署到Kubernetes集群。内部Jenkins作业负责在创建标签时将Docker镜像推送到Docker Hub并部署chart。Docker Hub仓库地址：https://hub.docker.com/r/coco/draft-annotations-api
• CI由CircleCI提供：draft-annotations-api

服务端点

有关服务API端点的完整描述，请参阅Open API规范。

GET - 从PAC读取草稿注释

使用curl：

bash
curl http://localhost:8080/draft/content/{content-uuid}/annotations | jq

此端点上的GET请求通过调用https://github.com/Financial-Times/generic-rw-aurora%E8%8E%B7%E5%8F%96%E7%89%B9%E5%AE%9A%E5%86%85%E5%AE%B9%E7%9A%84%E8%8D%89%E7%A8%BF%E6%B3%A8%E9%87%8A%E3%80%82%E6%88%90%E5%8A%9F%E6%97%B6%EF%BC%8C%E9%80%9A%E8%BF%87%E8%B0%83%E7%94%A8https://github.com/Financial-Times/concept-search-api%E4%B8%BA%E6%B3%A8%E9%87%8A%E6%B7%BB%E5%8A%A0%E6%A6%82%E5%BF%B5%E4%BF%A1%E6%81%AF%E3%80%82%E5%A6%82%E6%9E%9CPAC%E4%B8%AD%E6%B2%A1%E6%9C%89%E5%8F%AF%E7%94%A8%E7%9A%84%E6%B3%A8%E9%87%8A%EF%BC%8CDraft Annotations API会通过调用https://github.com/Financial-Times/public-annotations-api%E8%8E%B7%E5%8F%96%E5%B7%B2%E5%8F%91%E5%B8%83%E7%9A%84%E6%B3%A8%E9%87%8A%E3%80%82%E8%8E%B7%E5%8F%96%E5%B7%B2%E5%8F%91%E5%B8%83%E6%B3%A8%E9%87%8A%E6%98%AF%E5%9C%A8PAC%E4%B8%AD%E5%8A%A8%E6%80%81%E5%AF%BC%E5%85%A5%E9%81%97%E7%95%99%E6%B3%A8%E9%87%8A%E7%AD%96%E7%95%A5%E7%9A%84%E4%B8%80%E9%83%A8%E5%88%86%E3%80%82

响应体示例：

json
{
  "annotations": [
    {
      "predicate": "http://www.ft.com/ontology/annotation/hasAuthor",
      "id": "http://www.ft.com/thing/fd6734a1-3ae2-30f3-98a1-e373f8da8bf1",
      "apiUrl": "http://api.ft.com/people/fd6734a1-3ae2-30f3-98a1-e373f8da8bf1",
      "type": "http://www.ft.com/ontology/person/Person",
      "prefLabel": "Emily Cadman",
      "isFTAuthor": true
    },
    {
      "predicate": "http://www.ft.com/ontology/annotation/hasContributor",
      "id": "http://www.ft.com/thing/5bd49568-6d7c-3c10-a5b0-2f3fd5974a6b",
      "apiUrl": "http://api.ft.com/people/5bd49568-6d7c-3c10-a5b0-2f3fd5974a6b",
      "type": "http://www.ft.com/ontology/person/Person",
      "prefLabel": "Lisa Barrett",
      "isFTAuthor": true
    },
    {
      "predicate": "http://www.ft.com/ontology/annotation/about",
      "id": "http://www.ft.com/thing/d7de27f8-1633-3fcc-b308-c95a2ad7d1cd",
      "apiUrl": "http://api.ft.com/things/d7de27f8-1633-3fcc-b308-c95a2ad7d1cd",
      "type": "http://www.ft.com/ontology/Topic",
      "prefLabel": "Global economic growth"
    }
  ]
}

PUT - 向PAC写入草稿注释

使用curl：

bash
curl -X PUT \
  http://localhost:8080/drafts/content/{content-uuid}/annotations \
  -d '{
    "annotations": [
      {
        "predicate": "http://www.ft.com/ontology/annotation/hasContributor",
        "id": "http://www.ft.com/thing/5bd49568-6d7c-3c10-a5b0-2f3fd5974a6b",
        "apiUrl": "http://api.ft.com/people/5bd49568-6d7c-3c10-a5b0-2f3fd5974a6b",
        "type": "http://www.ft.com/ontology/person/Person",
        "prefLabel": "Lisa Barrett"
      },
      {
        "predicate": "http://www.ft.com/ontology/annotation/about",
        "id": "http://www.ft.com/thing/d7de27f8-1633-3fcc-b308-c95a2ad7d1cd",
        "apiUrl": "http://api.ft.com/things/d7de27f8-1633-3fcc-b308-c95a2ad7d1cd",
        "type": "http://www.ft.com/ontology/Topic",
        "prefLabel": "Global economic growth"
      },
      {
        "predicate": "http://www.ft.com/ontology/annotation/hasDisplayTag",
        "id": "http://www.ft.com/thing/d7de27f8-1633-3fcc-b308-c95a2ad7d1cd",
        "apiUrl": "http://api.ft.com/things/d7de27f8-1633-3fcc-b308-c95a2ad7d1cd",
        "type": "http://www.ft.com/ontology/Topic",
        "prefLabel": "Global economic growth"
      }
    ]
  }'

此端点上的PUT请求将草稿注释写入PAC。输入体是注释JSON对象数组，其中仅predicate和id是必填字段。如果写入操作成功，应用将返回规范化的输入体，并附带HTTP 200响应码。

规范化响应示例：

json
{
  "annotations": [
    {
      "predicate": "http://www.ft.com/ontology/annotation/hasContributor",
      "id": "http://www.ft.com/thing/5bd49568-6d7c-3c10-a5b0-2f3fd5974a6b"
    },
    {
      "predicate": "http://www.ft.com/ontology/annotation/about",
      "id": "http://www.ft.com/thing/d7de27f8-1633-3fcc-b308-c95a2ad7d1cd"
    },
    {
      "predicate": "http://www.ft.com/ontology/annotation/hasDisplayTag",
      "id": "http://www.ft.com/thing/d7de27f8-1633-3fcc-b308-c95a2ad7d1cd"
    }
  ]
}

DELETE - 从PAC中删除草稿编辑注释

使用curl：

bash
curl http://localhost:8080/draft/content/{content-uuid}/annotations/{concept-uuid} | jq

此端点上的DELETE请求从特定内容的编辑已发布注释中删除单个概念的所有注释。为了检索这些特定注释，它会使用“lifecycle”参数调用https://github.com/Financial-Times/public-annotations-api%E3%80%82%E5%A6%82%E6%9E%9C%E6%93%8D%E4%BD%9C%E6%88%90%E5%8A%9F%EF%BC%8C%E5%BA%94%E7%94%A8%E5%B0%86%E8%BF%94%E5%9B%9E%E8%A7%84%E8%8C%83%E5%8C%96%E7%9A%84%E8%BE%93%E5%85%A5%E4%BD%93%EF%BC%8C%E5%B9%B6%E9%99%84%E5%B8%A6HTTP 200响应码。

响应体示例：

json
{
  "annotations": [
    {
      "predicate": "http://www.ft.com/ontology/annotation/hasContributor",
      "id": "http://www.ft.com/thing/5bd49568-6d7c-3c10-a5b0-2f3fd5974a6b"
    },
    {
      "predicate": "http://www.ft.com/ontology/annotation/about",
      "id": "http://www.ft.com/thing/d7de27f8-1633-3fcc-b308-c95a2ad7d1cd"
    },
    {
      "predicate": "http://www.ft.com/ontology/annotation/hasDisplayTag",
      "id": "http://www.ft.com/thing/d7de27f8-1633-3fcc-b308-c95a2ad7d1cd"
    }
  ]
}

健康检查

管理端点包括：

• /__gtg
• /__health
• /__build-info

目前，/__health和/__gtg检查UPP Public Annotations API的可用性。

日志

• 应用使用https://github.com/sirupsen/logrus%EF%BC%9B%E6%97%A5%E5%BF%97%E5%99%A8%E5%9C%A8main.go%E4%B8%AD%E5%88%9D%E5%A7%8B%E5%8C%96%E3%80%82
• 日志输出到标准输出。
• 注意：/__build-info和/__gtg端点不会被记录，因为它们每秒都会被varnish/vulcand调用，这些信息在日志/Splunk中不需要。