clariah/grlc

grlc：git仓库关联数据API构造器

!https://raw.githubusercontent.com/CLARIAH/grlc/master/src/static/grlc_logo_01.png

镜像概述和主要用途

grlc是一个轻量级服务器，可将SPARQL查询（存储在GitHub仓库、本地文件系统或URL中）自动转换为Linked Data Web API。它允许用户无需了解SPARQL即可通过Web API访问关联数据，提供Swagger UI风格的API文档，支持多种查询位置和丰富的装饰器功能，实现关联数据的通用访问。

核心功能和特性

• 多查询位置支持：从GitHub仓库、本地文件系统或Web规范文件加载SPARQL查询集合
• 自动API生成：为每个SPARQL查询（.rq文件）创建对应的API操作
• 参数映射：支持将SPARQL查询变量映射为API参数，实现动态查询
• 装饰器系统：通过查询注释添加元数据（摘要、描述、端点等），增强API功能
• Swagger UI集成：自动生成交互式API文档，支持在线测试和探索
• 结果处理：支持分页、结果转换（SPARQLTransformer）和内容协商
• 版本控制：支持基于GitHub提交SHA生成特定版本的API

使用场景和适用范围

• 开发人员：将SPARQL查询转换为RESTful API，简化关联数据访问
• 数据发布者：为关联数据集提供用户友好的API访问接口
• 研究人员：共享SPARQL查询并提供标准化API访问方式
• 教育场景：降低关联数据使用门槛，无需深入学习SPARQL

详细使用方法和配置说明

查询位置

grlc支持从三种位置加载查询集合，所有位置类型均生成相同格式的API。

从GitHub仓库

API路径：http://grlc-server/api-git/<user>/<repo>

通过GitHub用户名（<user>）和仓库名（<repo>）指定仓库，例如：

http://grlc.io/api-git/CLARIAH/grlc-queries/

支持功能：

• 版本控制：通过提交SHA指定版本：http://grlc-server/api-git/<user>/<repo>/commit/<sha>
• 子目录：指定仓库内子目录：http://grlc-server/api-git/<user>/<repo>/subdir/<subdir>

从本地存储

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

从grlc服务器运行所在机器的本地目录加载查询，目录位置通过配置文件设置。本地目录中可包含local-api-config.ini配置文件：

ini
[repo_info]
repo_title = API标题
api_description = API描述
contact_name = 联系人
contact_url = 联系URL
licence_url = 许可证URL

从规范文件

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

从Web上的YAML规范文件加载查询，例如：

http://grlc.io/api-url?specUrl=https://raw.githubusercontent.com/CLARIAH/grlc-queries/master/urls.yml

规范文件语法：

yaml
title: API标题
description: API描述
contact:
  name: 联系人名称
  url: 联系人URL
licence: 许可证URL
queries:
  - https://example.com/query1.rq
  - https://example.com/query2.rq

生成的API

• API文档：访问API路径即可查看Swagger UI风格的交互式文档
• Swagger规范：通过<API-path>/swagger获取API的Swagger规范

查询执行

调用API端点时，grlc会结合参数和装饰器执行SPARQL查询，结果以rdflib.query.QueryResult的JSON表示返回。指定SPARQL端点的方式：

1. 在配置文件中设置sparql_endpoint
2. 在请求中添加endpoint参数：http://grlc.io/user/repo/query?endpoint=http://sparql-endpoint/
3. 在查询中添加#+ endpoint:装饰器
4. 在GitHub仓库中添加endpoint.txt文件（单行包含端点URL）

装饰器语法

装饰器以#+ 开头，作为SPARQL查询注释添加，支持以下类型：

summary

为API操作添加摘要，显示在Swagger UI中：

sparql
#+ summary: 查询摘要说明

description

为API操作添加详细描述：

sparql
#+ description: 这是查询的详细描述文本

endpoint

指定查询使用的SPARQL端点：

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

pagination

启用结果分页，指定每页数量：

sparql
#+ pagination: 100

method

指定HTTP请求方法（GET/POST）：

sparql
#+ method: POST

tags

为操作添加标签，用于在Swagger UI中分组：

sparql
#+ tags:
#+   - 标签1
#+   - 标签2

defaults

设置参数默认值：

sparql
#+ defaults:
#+   - param_name: default_value

enumerate

为参数提供枚举值（在Swagger UI中显示为下拉菜单）：

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

endpoint_in_url

控制是否允许在URL中指定endpoint参数：

sparql
#+ endpoint_in_url: False

transform

使用SPARQLTransformer语法转换JSON响应结构：

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

Docker部署示例

基本运行

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

带环境变量配置

bash
docker run -it --rm -p 8088:80 \
  -e GRLC_SERVER_NAME=grlc.io \
  -e GRLC_GITHUB_ACCESS_TOKEN=your_github_token \
  -e GRLC_SPARQL_ENDPOINT=http://dbpedia.org/sparql \
  -e DEBUG=true \
  docker.xuanyuan.run/clariah/grlc

环境变量配置说明

示例API

• [***]
• [***]
• [***]