SPARQList

提供：TogoWiki

SPARQList は SPARQL クエリの結果を（必要なら JavaScript で加工して）クライアントに返す REST API を提供するためのミドルウェアです。

目次 1 主な機能 2 レポジトリ 3 インストール 4 起動方法 4.1 デプロイ例 4.2 おまけ 5 使い方 6 Dockerfile

主な機能

• Markdown で SPARQL クエリのドキュメントが書ける
• SPARQL の結果を JavaScript で任意に加工できる
• 多段の SPARQL や JavaScript の結果を組み合わせて最終的なデータを生成できる
• ウェブの UI から REST API のロジックを編集したり、オプションを変更できる
• コンテントネゴシエーションで json の他に text や csv など色々なデータを返すこともできる

レポジトリ

• https://github.com/dbcls/sparqlist

インストール

node.js の最新版をインストール（展開して bin/node, bin/npm を ~/local/bin などにリンクする）

$ wget --no-check-certificate https://nodejs.org/dist/v7.7.2/node-v7.7.2-linux-x64.tar.xz
$ npm install yarn -g

sparql-proxy の現状版をダウンロードしてインストール

$ git clone https://github.com/dbcls/sparqlist.git
$ cd sparqlist
$ ROOT_PATH=/rest/ yarn install

ここで ROOT_PATH=/rest/ は http://localhost:3000/ の代わりに http://localhost:3000/rest/ などのサブパスに SPARQList をデプロイするための設定。

起動方法

$ ROOT_PATH=/rest/ PORT=3000 ADMIN_PASSWORD=xxxxx yarn start

これで http://localhost:3000/rest/ を開けば OK。

デプロイ例

• http://dev.togogenome.org/rest/

おまけ

デーモン化する場合

$ npm install forever -g

インストール先が /opt/sparqlist/git で yarn が /opt/sparqlist/local/bin にある場合

$ cat startup.sh
#!/bin/sh

export PATH="/opt/sparqlist/local/bin:$PATH"
(cd /opt/sparqlist/git; ROOT_PATH=/rest/ PORT=xxxxx ADMIN_PASSWORD=xxxxx forever --workingDir=/opt/sparqlist/git /opt/sparqlist/local/bin/yarn start > yarn.log)

使い方

Markdown で SPARQL クエリや JavaScript を記述する。

# Organism images

## Parameters

* `tax` Taxonomy ID
  * default: 4896
  * examples: 9606, 4896, ...

## Endpoint

http://dev.togogenome.org/sparql-test

## `result` Image URLs

```sparql
PREFIX up: <http://purl.uniprot.org/core/>
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
SELECT ?tax ?up_uri ?id_uri ?image
WHERE {
  VALUES ?tax { "{{params.tax}}" }
  VALUES ?up_uri { <http://purl.uniprot.org/taxonomy/{{params.tax}}> }
  VALUES ?id_uri { <http://identifiers.org/taxonomy/{{params.tax}}> }
  ?up_uri foaf:depiction ?image
}
```

## Output

```javascript
({
  json({result}) {
    return result.results.bindings;
  },
  text({result}) {
    // return result.results.bindings.map(function(row) {
	// return result.results.bindings.map((row) => {  // same as above
	// return result.results.bindings.map(row => {    // same as above
	//   return row.image.value;
	// }).join("\n");
    return result.results.bindings.map(row => row.image.value).join("\n");  // same as above
  }
})
```

このようなファイルを repository ディレクトリ以下に置くことでファイル名を API 名として提供できる。 起動時に指定した ADMIN_PASSWORD で Login すると、ウェブブラウザ上でも API を作成したり編集したりできる。

• ドキュメントは自由に記述可能
• 最初の # 行が API の名前になる
• ## Parameters に `hoge` のようにクオートすることで引数の変数名を指定
  • 変数の説明は自由に記述可能
  • デフォルト値はインデントして default: に続けて記載
  • 他に examples: などを追記することを推奨
• ## Endpoint にエンドポイントの URL を記述
• 続く ## セクションは、`foo` などで結果を受け取る変数名を指定、説明文は自由に記述可能
  • コードは ```sparql か ```javascript のブロックで記載
• 最後のセクションの戻り値が API の戻り値となる
  • 最後のセクションが ```sparql の場合、ユーザからの Accept ヘッダがそのまま渡されるため、SELECT 以外の SPARQL に使える
  • 最後のセクションが ```javascript の場合、json() や text() などの関数を並べることで content negotiation する API に拡張できる → この場合 API の拡張子に .json や .text をつけることでも呼び出せるようになる。

Dockerfile

SPARQLthon55 で SPARQList の Dockerfile を作りました。

• https://gist.github.com/ktym/c733743b0c58ccf4ca8b825a1fd06d88

% docker build -t sparqlist:v1.0 .
% docker run -d -p 80:3000 sparqlist:v1.0
a1ab8042c9a83b0a0e95a7c0b02c3a13e9ce460ca4aed93d59918f17d2bf533c

http://localhost/sparqlist で見れるはずです。デプロイ例 → http://ep.dbcls.jp/sparqlist/