検索結果と検索履歴をJSONで返すAPIを提供しています。search, clearの2つのメソッドで実現します。 検索条件やセッションIDは、URLパラメータまたはリクエストbody(JSON)で指定します。重複する指定の場合、リクエストbodyよりURLパラメータの方を優先します。

連続して検索する場合には、検索履歴を活用できます。 初回の検索時にsearchメソッドで返ってくるセッションIDを以降の検索時にパラメータで渡してください。検索結果と合わせて検索履歴が保持されます。 検索履歴は、clearメソッドでクリアできます。

(1) searchメソッド (GET/POST)

searchメソッドは、用語を検索するためのものです。 以下のようなURLになります。URLパラメータやリクエストbodyで既存のセッションIDと検索条件を渡します。

(a) http://squaring.jp/api/term/search? word=error (GET)
(b) http://squaring.jp/api/term/search? cid=03&matching=1&align=4&word=error (GET)

(c) http://squaring.jp/api/term/search? sid=1010001&cid=03&matching=1&align=4 &word=error (GET)
(d) http://squaring.jp/api/term/search (POST)
    body:{
      "sid":1010001,
      "cid":"00",
      "matching":1,
      "align":4,
      "word":"error"
    }

• 上記の(a),(b)はリンクになっているのでクリックしてみてください。検索結果がJSONが返ってきます。
• 用語検索ツールは、このAPIを使って実装しています。

• 検索ワード(wordパラメータ)の指定は必須であり、省略すると検索結果は0件となります。 検索ワードの指定方法は、完全一致・部分一致の検索を参照ください。複合条件検索、索引検索、述語検索、出典検索、AID検索も同じwordパラメータを使います。
• sid,cid,matching,align,clearパラメータはオプションです。省略すると、以下のように判定されます。
  ・ sid=0 : セッションID指定なし
  ・ cid=03 : テスティング辞書
  ・ matching=2 : 見出語・同義語の部分一致
  ・ align=4 : 日本語WORDで昇順ソート
  ・ clear=0 : 履歴をクリアしない
• 既存のセッションIDをパラメータとして渡すと、そのセッションIDが有効であれば、サーバー側で検索履歴が保持されます。

javascriptから呼び出す場合は、以下のコードを参照ください。リクエストbodyでセッションID(sid)と検索条件を渡します。[検索]ボタンのonclickなどから呼び出すようにします。

function search(form){
  // クライアント側でキャッシュからSIDを取得する。
  // また、検索条件はフォームから取得する。
  var sid = getSidFromCache();
  var params = {};
  params['sid'] = sid;
  params['cid'] = form.cid.value;
  params['matching'] = toInt(form.matching.value);
  params['word'] = form.word.value;
  params['align'] = toInt(form.align.value);
  params['clear'] = 0;
  // パラメータをJSONにセットして、searchメソッド
  // をPOSTで呼び出す。
  fetch('http://squaring.jp/api/term/search', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify(params)
  })
  .then(response => response.json())
  .then(json => {
    if (sid != json.sid){
      // SIDを指定しなかった場合や有効でない
      // 場合にはゲスト用IDが生成される。
      // SIDを次回の検索用にキャッシュしておく。
      putSidToCache(json.sid);
    }
    // レスポンスから条件・結果・履歴を取得する。
    // 検索条件
    var conditions = json.conditions;
    // APIで許可される最大件数(50件)
    var limit = conditions.limit;
    // DB内の該当するデータ件数
    var count = json.count;
    // 検索結果(用語の配列)
    var terms = json.terms;
    // 検索履歴
    var histories = json.histories;
    // TODO ここで検索条件・検索結果・検索
    // 履歴をもとにHTMLを生成する。
  });
}
function toInt(x){ return isNaN(x)? 0 : Number(x); }
function getSidFromCache(){ return toInt(window.sessionStorage['sid']); }
function putSidToCache(sid){ window.sessionStorage['sid'] = sid; }

alignパラメータは、検索結果のソートに使用します。表示するフィールドと表示順を参照ください。 また、検索件数が上限(limit)を超える場合には50件分のデータしか返しませんが、DB内のデータの実数はcountで知ることができます。 レスポンスJSONは、以下ようになります。

{
  "sid":1010001,
  "conditions":{
    "cid":"00",
    "matching":2,
    "limit":50,
    "align":4,
    "word":"error"
  },
  "count":28,
  "message":"用語は 28 件ありました。",
  "terms":[
    {
      "seq_no":1,
      "cid":"01",
      "word":"動的エラー",
      "word_en":"dynamic error",
      "synonym":"",
      "synonym_en":"",
      "content":"入力の時間変化する性質に依存した エラー。[SSEV]",
      "content_en":"an error that is dependent on the time-varying nature of an input. [SSEV]",
      "explanation":"※`静的エラー`も参照のこと。",
      "aid":964,
      "one":"ト",
      "one_en":"D",
      "updated":"2024/02/07 09:38:23"
    },
    ... (中略)
  ],
  "histories":["mistake","error"]
}

検索履歴がhistoriesで返ってきます。上記の例では、今回の検索がword="error"で、その前の検索がword="mistake"であったことを示しています。

検索結果のテキスト(content, content_en, explanation)には、リンク情報や出典情報を含んでいます。 ネストして検索したい用語はバッククォート「``」で挟み込んでいます。出典情報は鍵括弧「[]」で挟み込んでいます。 改行は「\r」や「\n」になっています。 これらをHTMLに変換するためのライブラリとして glossary-replacer.js を用意しています。UTF-8の扱えるエディタで参照ください。

このライブラリでは、ネストして検索したい場合は、goT(word)の関数を呼び出すように記述しています。以下を参考にしてください。

function goT(word){
  // 検索ワードをフォームにセットする。
  var form = document.forms["terms"];
  form.word.value = word;
  // ネストして検索する。
  search(form);
  // 先頭から表示させる。
  window.scrollTo(0, 0);
  return false;
}

(2) clearメソッド (POST)

clearメソッドは、サーバー側で保持する検索履歴をクリアするためのものです。 クライアント側で[クリア]ボタンなどを実装するときに使用します。リクエストbodyで既存のセッションID(sid)を渡します。 searchメソッドでclearオプションを指定した場合、このclearメソッドが適用され、検索の前に履歴がクリアされます。

javascriptから呼び出す場合は、以下のコードを参照ください。リクエストbodyで既存のセッションIDを渡します。[クリア]ボタンのonclickなどから呼び出すようにします。

function clear(){
  // クライアント側でキャッシュからSIDを取得する。
  var sid = getSidFromCache();
  if (sid > 0){
    // JSONにSIDをセットして、clearメソッド
    // をPOSTで呼び出す。
    // clearメソッドには、レスポンスはない。
    var params = {'sid':sid};
    fetch('http://squaring.jp/api/term/clear',
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: JSON.stringify(params)
    });
  }
}
function toInt(x){ return isNaN(x)? 0 : Number(x); }
function getSidFromCache(){ return toInt(window.sessionStorage['sid']); }