Fessのバージョン14.8では、検索利用者向けAPIがOpenAPI仕様に変更されました。この変更により、APIの利用がより簡単かつ柔軟になり、開発者がFessの機能を利用しやすくなっています。今回は、新しいAPIの概要と基本的な利用方法について紹介します。

また、従来のAPIを利用したい場合は、fess-webapp-classic-apiプラグインをインストールすることで利用することができます。過去のAPIと互換性が必要な場合はご利用ください。

APIの種類

Fessが提供している検索利用者向けAPIは以下のとおりです。

  • 検索API
  • ラベルAPI
  • 人気ワードAPI
  • サジェストAPI
  • ヘルスチェックAPI

これらのAPIはJSON形式でレスポンスを返すため、設定で「JSONレスポンス」が有効になっていることを確認してください。この設定は、管理画面の左メニュー「システム」＞「全般」を選択し、全般設定の画面で「JSONレスポンス」で確認できます。「JSONレスポンス」にチェックが入っていない場合は、チェックを入れて「更新」ボタンをクリックして設定を保存してください。

検索APIの利用方法

各APIの基本的なリクエスト方法とレスポンス例を以下に示します。

今回のAPI群に関するOpenAPIドキュメントは、openapi-user.yamlで参照できます。

検索API

検索APIはFessの検索結果を返します。リクエストは以下の形式で送信します。

http://<Server Name>/api/v1/documents?q=検索語

実際にcurlコマンドを使って検索してみます。検索語(q=opensearch)、ラベルの値(fields.label=fess)、表示件数(num=5)を指定した場合、以下のレスポンスが返ります。（実行結果はjqコマンドで整形しています）

data[]内が、ヒットした検索結果です。その他のリクエストパラメーター、レスポンスについてはこちらを参照してください。

$ curl "http://localhost:8080/api/v1/documents?q=opensearch&fields.label=fess&num=5" | jq .
{
  "q": "opensearch",
  "query_id": "614ef4df66f24b9abc1d914984e915fb",
  "exec_time": 0.03,
  "query_time": 26,
  "page_size": 5,
  "page_number": 1,
  "record_count": 7,
  "record_count_relation": "EQUAL_TO",
  "page_count": 2,
  "highlight_params": "&hq=fess&hq=opensearch",
  "next_page": true,
  "prev_page": false,
  "start_record_number": 1,
  "end_record_number": 5,
  "page_numbers": [
    "1",
    "2"
  ],
  "partial": false,
  "search_query": "opensearch label:\"fess\"",
  "requested_time": 1708424827135,
  "related_query": [],
  "related_contents": [],
  "data": [
    {
      "filetype": "html",
      "title": "オープンソース全文検索サーバー Fess",
      "content_title": "オープンソース全文検索サーバー <strong>Fess</strong>",
      "digest": "Fess (フェス) は「5 分で簡単に構築可能な全文検索サーバー」です。",
      "host": "fess.codelibs.org",
      "last_modified": "2024-02-20T02:59:47.000Z",
      "content_length": "39745",
      "timestamp": "2024-02-20T02:59:47.000Z",
      "url_link": "https://fess.codelibs.org/ja/index.html",
      "created": "2024-02-20T06:59:31.245Z",
      "site_path": "fess.codelibs.org/ja/index.html",
      "doc_id": "62d136ccbae7428a88a531b17880f519",
      "url": "https://fess.codelibs.org/ja/index.html",
      "content_description": "Java環境またはDocker環境で利用（OS非依存) <strong>OpenSearch</strong>またはElasticsearchを検索エンジンとして利用...",
      "site": "fess.codelibs.org/ja/index.html",
      "filename": "index.html",
      "boost": "1.0",
      "mimetype": "text/html",
      "_id": "84f87ca116cd36ecb8faf758d0a5d5bdfec8de6a0c90c747040ee2fd684666ad08fa094f5007ccb88a1af9494833b7ceb826c870a63eff1645f54b044c12bbfc"
    },
    ・
    ・
    ・
  ]
}

ラベルAPI

ラベルAPIは、Fessに登録されているラベルの一覧を返します。リクエストパラメーターとレスポンスについてはこちらを参照してください。

 http://<Server Name>/api/v1/labels

以下のようなレスポンスが返ってきます。

$ curl  http://localhost:8080/api/v1/labels | jq .
{
  "record_count": 2,
  "data": [
    {
      "label": "FESS",
      "value": "fess"
    },
    {
      "label": "OpenSearch",
      "value": "opensearch"
    }
  ]
}

人気ワードAPI

Fess で最もよく検索された検索語の一覧を返します。

人気ワードAPIを使う場合、「人気ワードのレスポンス」の設定を有効にする必要があります。デフォルトの設定では有効になっていますが、レスポンスが返ってこない場合は、この設定が有効になっているかを確認してください。この設定も全般設定の画面で確認できます。

リクエスト形式は以下です。リクエストパラメーター、レスポンスについてはこちらを参照してください。

http://<Server Name>/api/v1/popular-words

以下のようなレスポンスが返ってきます。

$ curl  http://localhost:8080/api/v1/popular-words | jq .
{
  "record_count": 3,
  "data": [
    "java",
    "install",
    "test"
  ]
}

サジェストAPI

Fess に登録されているサジェストワードの一覧を返します。

サジェストAPIを使う場合、「検索語でサジェスト」または「ドキュメントでサジェスト」の設定を有効にする必要があります。デフォルトの設定では有効になっていますが、レスポンスが返ってこない場合は、この設定が有効になっているかを確認してください。この設定も全般設定の画面で確認できます。

リクエスト形式は以下です。リクエストパラメーター、レスポンスについてはこちらを参照してください。

http://<Server Name>/api/v1/suggest-words?q=サジェストワード

以下はサジェストワード(q=java)、サジェストされる件数(num=5)を指定して、リクエストを投げた場合の例です。

$ curl  "http://localhost:8080/api/v1/suggest-words?q=java&num=5" | jq .
{
  "query_time": 2,
  "record_count": 4,
  "page_size": 4,
  "data": [
    {
      "text": "java",
      "labels": [
        "opensearch",
        "fess"
      ]
    },
    {
      "text": "javascript",
      "labels": [
        "opensearch"
      ]
    },
    {
      "text": "javadoc",
      "labels": [
        "opensearch"
      ]
    },
    {
      "text": "javadocs",
      "labels": [
        "opensearch"
      ]
    }
  ]
}

ヘルスチェックAPI

Fess のサーバーの状態を返します。

リクエストパラメーター、レスポンスについてはこちらを参照してください。

http://<Server Name>/api/v1/health

サーバーの状態が正常であればgreenを返します。

$ curl http://localhost:8080/api/v1/health | jq .
{
  "data": {
    "status": "green",
    "timed_out": false
  }
}

*　*　*

Fessのバージョン14.8以降、検索用APIがOpenAPI仕様に刷新され、開発者はより簡単かつ柔軟にFessの検索機能を利用できるようになりました。この変更で、アプリケーション開発の効率を改善できるようになると思います。提供されているAPI群（検索API、ラベルAPI、人気ワードAPI、サジェストAPI、ヘルスチェックAPI）を通じて、高度な検索機能をウェブサイトやアプリケーションに容易に組み込むことが可能です。この機会にぜひ、Fessの新しいAPIをお試しください。