SPARQList

提供:TogoWiki

移動: 案内, 検索

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

目次

主な機能

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

レポジトリ

インストール

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。

デプロイ例

おまけ

デーモン化する場合

$ 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}}" }   ### SPARQList Ver. 2018-02-07 以降では 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 をつけることでも呼び出せるようになる。

fetch

  • 2018/02/20 ver.から javascript 内で "fetch" が使えるようになった
    • SPARQLet や他のAPIが呼べる
    • body: や Content-Type などは API に合わせる
      • SPARQLet 呼ぶなら header は要らないみたい
```javascript
async({var1, var2})=>{
    const options = {
      method: 'POST',
      body: "key=" + encodeURIComponent(value),
      headers: {
        'Accept': 'application/sparql-results+json',
        'Content-Type': 'application/x-www-form-urlencoded'
      }
    };

    try{
      var res = await fetch('http://example.org/rest/api/hoge', options).then(res=>res.json());
      return res;
    }catch(error){
      console.log(error);
    }
};
```

Dockerfile

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

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

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

個人用ツール