grlc，Git仓库链接数据API构建器，通过使用共享的SPARQL查询自动构建Web API。 http://grlc.io/

如果您在工作中使用了grlc，请引用它：

@InProceedings{merono2016grlc,
 author = {Mero{\~{n}}o-Pe{\~{n}}uela, Albert and Hoekstra, Rinke},
 title = {{grlc Makes GitHub Taste Like Linked Data APIs}},
 booktitle = {The Semantic Web: ESWC 2016 Satellite Events, Heraklion, Crete, Greece, May 29 -- June 2,  2016},
 year = {2016},
 publisher = {Springer},
 pages = {342--353},
 isbn = {978-3-319-47602-5},
 doi = {10.1007/978-3-319-47602-5_48}
}

什么是grlc？

grlc是一个轻量级服务器，它接受SPARQL查询（存储在GitHub或GitLab仓库中，在您的本地文件系统中，或列在URL中），并将它们转换为链接数据Web API。这使链接数据具有通用访问性。用户无需知道SPARQL即可查询他们的数据，而是可以通过Web API进行访问。

快速教程

有关快速使用教程，请查看我们的wiki 概述 和 功能列表。

使用方法

grlc假定您有一组以.rq文件为SPARQL查询的集合（如 此）。grlc将为集合中的每个SPARQL查询/.rq文件创建一个API操作。

您可以通过使用参数映射语法为每个操作添加API参数。这允许您的查询定义查询变量，这些变量将被映射到API操作的API参数（请参见此处的示例）。

您的查询可以包含特殊的装饰器，以添加额外的功能到您的API。

查询位置

grlc可以从不同的位置加载您的查询集合：从GitHub仓库（api-git）、从GitLab仓库（api-gitlab）、从本地存储（api-local）以及从规范文件（api-url）。每种位置类型都有特定的功能和可访问的路径。然而，所有位置类型都生成相同的美丽API。

从GitHub仓库

API路径：http://grlc-server/api-git/<用户>/<仓库名>

grlc可以从任何GitHub仓库构建API，指定所有者（<用户>）的GitHub用户名和仓库名称（<仓库名>）。

例如，假设您的查询存储在GitHub仓库中：https://github.com/CLARIAH/grlc-queries/，将浏览器指向以下位置http://grlc.io/api-git/CLARIAH/grlc-queries/

grlc可以利用git的版本控制机制，根据仓库中特定版本的查询生成API。这可以通过在URL路径中包含提交sha（http://grlc-server/api-git/<用户>/<仓库名>/commit/<sha>）来实现，例如：http://grlc.io/api-git/CLARIAH/grlc-queries/commit/79ceef2ee814a12e2ec572ffaa2f8212a22bae23

grlc还可以使用GitHub仓库内的子目录。这可以通过在URL路径中包含子目录来实现（http://grlc-server/api-git/<用户>/<仓库名>/subdir/<子目录>）。

从GitLab仓库

API路径：http://grlc-server/api-gitlab/<用户>/<仓库名>

grlc可以从任何GitLab仓库构建API，指定所有者（<用户>）的GitLab用户名和仓库名（<仓库名>）。

例如，假设您的查询存储在GitLab仓库中：https://gitlab.com/c-martinez/grlc-queries，将浏览器指向以下位置http://grlc.io/api-gitlab/c-martinez/grlc-queries/

grlc可以利用git的版本控制机制，根据仓库中特定版本的查询生成API。这可以通过在URL路径中包含分支名称来实现（http://grlc-server/api-gitlab/<用户>/<仓库名>/branch/<分支>），例如：http://grlc.io/api-gitlab/c-martinez/grlc-queries/branch/master

grlc还可以使用GitLab仓库内的子目录。这可以通过在URL路径中包含子目录来实现（http://grlc-server/api-gitlab/<用户>/<仓库名>/subdir/<子目录>），例如：http://grlc-server/api-gitlab/c-martinez/grlc-queries/subdir/subdir。

从本地存储

API路径：http://grlc-server/api-local/

grlc可以从运行grlc服务器的计算机上的本地目录生成API。您可以在grlc服务器配置文件中配置此目录的位置。另请参阅如何安装和运行自己的grlc实例。

当API从本地目录生成时，API信息可以从该文件夹中的配置文件加载。此文件必须命名为local-api-config.ini，并且具有以下格式

[repo_info]
repo_title = Some title
api_description = Description of my API
contact_name = My name
contact_url = https://mypage/
licence_url = https://mylicence/

从规范文件

API路径：http://grlc-server/api-url/?specUrl=<specUrl>

grlc可以从网络上可访问的yaml规范文件生成API。

例如，假设您的查询列在规范文件中：https://raw.githubusercontent.com/CLARIAH/grlc-queries/master/urls.yml，将浏览器指向以下位置http://grlc.io/api-url?specUrl=https://raw.githubusercontent.com/CLARIAH/grlc-queries/master/urls.yml

规范文件语法

grlc API规范文件是一个YAML文件，它包含了创建grlc API所需的所有必要信息，最重要的是包含装饰和HTTP可引用的SPARQL查询的URL列表。该文件应包含以下字段

• title：我的API的标题
• description：API描述
• contact：API所有者的联系信息。这应包括name和url属性。
• licence：指向API许可文件的URL。
• queries：SPARQL查询的URL列表（带有头部装饰器）。或者，一个查询也可以定义为一个包含name和url的字典。

例如

title: Title of my API
description: Description of my API
contact:
  name: Contact Name
  url: https://www.mywebsite.org
licence: http://example.org/licence.html
queries:
  - https://www.mywebsite.org/query1.rq
  - https://www.mywebsite.org/query2.rq
  - https://www.otherwebsite.org/query3.rq
  - name: QueryFour
    url: https://www.mywebsite.org/query4.rq

grlc生成的API

所有位置类型的API路径都指向生成的swagger-ui风格API文档。在API文档页面上，您可以探索可用的API调用并执行单个API调用。

您还可以通过访问<API-path>/swagger查看您的API的swagger规范，例如：http://grlc.io/api-git/CLARIAH/grlc-queries/swagger

grlc查询执行

当您调用API端点时，grlc通过组合提供的参数和装饰器来执行该端点的SPARQL查询。

有4种方式可以指定您自己的端点

• 在您的config.ini配置文件中添加sparql_endpoint
• 在您的请求中添加endpoint参数：'http://grlc.io/user/repo/query?endpoint=http://sparql-endpoint/'。如果您不希望在API的swagger-ui中看到endpoint参数，可以添加#+ endpoint_in_url: False装饰器。
• 添加#+ endpoint: 装饰器。
• 在包含查询的GitHub仓库中，将端点的URL单独一行添加到endpoint.txt文件中。

端点调用将返回查询执行的JSON表示形式的结果，即rdflib.query.QueryResult（对于其他结果格式，您可以使用HTTP Accept头的内容协商）。对于JSON响应，可以使用#+ transform: 装饰器修改响应的架构。

装饰器语法

提供了一些特殊的装饰器，可以使您的swagger-ui看起来更美观并增加功能。这些装饰器作为注释提供在查询文件的开始处，使其仍然语法上有效的SPARQL。所有装饰器都以#+ 开头，例如

#+ decorator_1: decorator value
#+ decorator_1: decorator value

SELECT * WHERE {
  ?s ?p ?o .
}

以下是一个可用装饰器和它们的功能列表

summary

创建查询/操作的摘要。这将在swagger-ui中显示在操作名称旁边。

语法

#+ summary: This is the summary of my query/operation

示例 查询 和等效的 API操作。

description

创建查询/操作的描述。这将在swagger-ui中显示为操作描述。

语法

#+ description: Extended description of my query/operation.

示例 查询 和等效的 API操作。

endpoint

指定特定的查询端点。

语法

#+ endpoint: http://example.com/sparql

示例 查询 和等效的 API操作。

pagination

以（例如）100个结果为一组分页。提供到上一页、下一页、第一页和最后一页结果的链接作为HTTP响应头，以避免污染有效负载（详细信息请参阅此处）

语法

#+ pagination: 100

示例 查询 和等效的 API操作。

method

指示HTTP请求方法（支持GET和POST）。

语法

#+ method: GET

示例 查询 和等效的 API操作。

tags

将标签分配给您的查询/操作。具有相同标签的查询/操作在swagger-ui中一起分组。

语法

#+ tags:
#+   - firstTag
#+   - secondTag

示例 查询 和等效的 API操作。

defaults

在swagger-ui中设置查询中特定参数的默认值。

语法

#+ defaults:
#+   - param_name: default_value

示例 查询 和等效的 API操作。

enumerate

指示您的查询/操作中哪些参数应该获取枚举值（并在swagger-ui中获取下拉菜单），使用SPARQL端点提供的给定值。每个枚举变量的值也可以在查询装饰器中指定，以节省端点请求并加快API生成。

语法

#+ enumerate:
#+   - var1:
#+     - value1
#+     - value2

示例查询和等效的API操作。

请注意，这些应该是普通的变量名，而不应使用SPARQL/BASIL约定（因此使用var1而不是?_var1_iri）

endpoint_in_url

允许/不允许将endpoint参数作为URL参数提供（默认允许）。

语法

#+ endpoint_in_url: False

示例查询和等效的API操作。

transform

允许使用SPARQLTransformer语法将查询结果转换为指定的JSON结构。请注意，必须将响应内容类型设置为application/json才能使转换生效。

语法

#+ transform: {
#+     "key": "?p",
#+     "value": "?o",
#+     "$anchor": "key"
#+   }

示例查询和等效的API操作。

endpoint-method

允许将查询通过grlc服务器发送到SPARQL端点，使用GET或POST http方法。默认：POST

语法

#+ endpoint-method: GET

示例查询和等效的API操作。

示例API

查看这些

• http://grlc.io/api-git/CLARIAH/grlc-queries
• http://grlc.io/api-gitlab/c-martinez/grlc-queries
• http://grlc.io/api-url?specUrl=https://raw.githubusercontent.com/CLARIAH/grlc-queries/master/urls.yml
• http://grlc.io/api-git/CLARIAH/wp4-queries-hisco
• http://grlc.io/api-git/albertmeronyo/lodapi
• http://grlc.io/api-git/albertmeronyo/lsq-api
• https://grlc.io/api-git/CEDAR-project/Queries

您可以在GitHub中找到这些以及其他许多来源。

使用此GitHub搜索查看其他grlc用户的示例。

安装和运行

您可以使用多种方式使用grlc

• 通过grlc.io：您可以使用grlc.io服务
• 通过Docker：您可以使用grlc docker镜像并启动自己的grlc服务器。
• 通过pip：您可以在您的机器上安装grlc。Grlc已在PyPi注册，因此您可以使用pip安装它。

以下将提供每个选项的更多详细信息。

grlc.io

使用grlc的最简单方法是访问grlc.io并使用此服务将SPARQL查询转换为RESTful API。您的查询可以存储在github仓库中或可以列在规范文件中。

Docker

要使用docker运行grlc，您需要一个工作的docker安装。要部署grlc，只需从Docker hub拉取最新的镜像。

docker run -it --rm -p 8088:80 clariah/grlc

docker镜像允许您设置多个环境变量，例如GRLC_SERVER_NAME、GRLC_GITHUB_ACCESS_TOKEN、GRLC_GITLAB_ACCESS_TOKEN和GRLC_SPARQL_ENDPOINT。

docker run -it --rm -p 8088:80 -e GRLC_SERVER_NAME=grlc.io -e GRLC_GITHUB_ACCESS_TOKEN=xxx -e GRLC_GITLAB_ACCESS_TOKEN=yyy -e GRLC_SPARQL_ENDPOINT=http://dbpedia.org/sparql -e DEBUG=true clariah/grlc

Pip

如果您想在本地运行grlc或将其用作库，您可以在您的机器上安装grlc。Grlc已在PyPi注册，因此您可以使用pip安装它。

先决条件

grlc有以下要求

• Python3
• 开发文件（根据您的操作系统而定）

sudo apt-get install libevent-dev python-all-dev

pip 安装

一旦满足基本要求，您可以像这样安装 grlc

pip install grlc

一旦安装了 grlc，您有几个选项

• 独立服务器
• 使用 WSGI 服务器
• 作为 Python 库

独立服务器

grlc 包含一个命令行工具，您可以使用它来启动自己的 grlc 服务器

grlc-server

使用 WSGI 服务器

您可以使用如下所示的 WSGI 服务器（如 gunicorn）来运行 grlc

gunicorn grlc.server:app

如果您想使用自己的 gunicorn 配置，例如 gunicorn_config.py

workers = 5
worker_class = 'gevent'
bind = '0.0.0.0:8088'

然后您可以这样运行它

gunicorn -c gunicorn_config.py grlc.server:app

注意：由于 gunicorn 在 Windows 上不工作，您可以使用 waitress 来代替

waitress-serve --port=8088 grlc.server:app

如果您想以服务的形式在系统启动时运行 grlc，您可以在 upstart/ 中找到示例 upstart 脚本

grlc 库

您可以直接从您的 Python 脚本中使用 grlc 作为库。请参阅 使用示例 了解更多信息。

grlc 服务器配置

无论您如何运行您的 grlc 服务器，您都需要使用 config.ini 文件进行配置。请查看 示例配置文件 以了解该文件的结构。

配置文件包含以下变量

• github_access_token 与 Github API 通信的 访问令牌。
• gitlab_access_token 与 GitLab API 通信的 访问令牌。
• local_sparql_dir 存储本地查询的本地存储目录。
• server_name 服务器的名称（例如 grlc.io）
• sparql_endpoint 默认 SPARQL 端点
• user 和 password SPARQL 端点的默认身份验证（如有必要，指定 'none' 以表示不需要）
• debug 启用调试级别日志。
• gitlab_url 指定您的 GitLab 实例的基础 URL。

Git 访问令牌

为了让 grlc 能够与 GitHub 和/或 GitLab 通信，您需要告诉 grlc 您的访问令牌是什么

1. 获取 GitHub 个人访问令牌 或 GitLab 个人访问令牌。
2. 您将获得一个访问令牌字符串，将其复制并保存在安全的地方。
3. 编辑您的 config.ini（分别为 github_access_token 和 gitlab_access_token）和/或 docker-compose.yml（分别为 GRLC_GITHUB_ACCESS_TOKEN 和 GRLC_GITLAB_ACCESS_TOKEN 环境变量）。

贡献！

grlc 需要 您 继续将语义网内容带给开发者、应用程序和用户。无论您只是一个好奇的用户、一个开发者还是研究人员；都有许多方式您可以进行贡献

• 提交错误报告
• 请求新功能
• 设置您自己的环境并开始开发

请查看我们的 贡献指南 了解这些及其他方式，并加入我们吧！

如果您不能编写代码，那没有问题！您仍然可以做出很多贡献

• 在 Twitter 上分享您使用 grlc 的经验（提及 @grlcldapi）
• 如果您擅长 HTML/CSS，让我们知道

相关工具

• SPARQL2Git 是一个用于编辑 SPARQL 查询并将其保存为 grlc API 的 GitHub 网络界面。
• grlcR 是一个 R 包，它通过 grlc 将链接数据轻松地引入您的 R 环境。
• Hay的工具 将grlc列为一个与维基媒体相关的工具 :-)

以下是grlc用户所说的话

• 用grlc为您的Linked Data增香，作者：Carlos Martinez
• 将任何SPARQL端点转换为OpenAPI，作者：Egon Willighagen

来自grlc用户的引用

一个可以将随机SPARQL端点转换为OpenAPI端点的酷项目

它使我们能够快速集成任何新的API需求，只需几秒钟，无需担心系统的配置或部署

您可以将您的SPARQL查询存储在GitHub上，然后您可以使用Web API（包括swagger文档）在您喜欢的编程语言（Python、JavaScript等）中运行查询，就像从网页加载数据一样简单

贡献者： Albert Meroño，Rinke Hoekstra，Carlos Martínez

版权： Albert Meroño，Rinke Hoekstra，Carlos Martínez
许可证： MIT许可证（见LICENSE.txt）

学术出版物

• Albert Meroño-Peñuela，Carlos Martinez-Ortiz. “grlc：git仓库链接数据API构建器。“开源软件杂志，6(67)，2731（2021），https://doi.org/10.21105/joss.02731
• Albert Meroño-Peñuela，Pasquale Lisena，Carlos Martínez-Ortiz. “知识图谱的Web数据API：简化应用开发人员对语义数据的访问”。数据、语义和知识综合讲座，12(1)，第1-118页（2021）（Morgan & Claypool）https://doi.org/10.2200/S01114ED1V01Y202107DSK021
• Albert Meroño-Peñuela，Rinke Hoekstra. “grlc使GitHub具有链接数据API的味道”。语义网 – ESWC 2016卫星活动，克里特岛赫拉克利翁，希腊，2016年5月29日至6月2日，修订选集论文。LNCS 9989，第342-353页（2016）。(PDF)
• Albert Meroño-Peñuela，Rinke Hoekstra. “SPARQL2Git：通过Git进行透明的SPARQL和链接数据API整理”。在：第14届扩展语义网会议（ESWC 2017），海报和演示轨道。斯洛文尼亚波尔托罗茨，2017年5月28日至6月1日（2017年）。(PDF)
• Albert Meroño-Peñuela，Rinke Hoekstra. “自动查询中心API，用于常规访问链接数据”。在：语义网 – ISWC 2017，第16届国际语义网会议。计算机科学讲座笔记，第10587卷，第334-339页（2017年）。(PDF)
• Pasquale Lisena，Albert Meroño-Peñuela，Tobias Kuhn，Raphaël Troncy. “使用SPARQL Transformer轻松开发Web API”。在：语义网 – ISWC 2019，第18届国际语义网会议。计算机科学讲座笔记，第11779卷，第454-470页（2019年）。(PDF)