お気に入りAPI

このドキュメントでは、 Fess の v2 お気に入り API について説明します。 共通のレスポンスエンベロープ・エラーモデル・CSRF については APIの概要 を参照してください。

ベースURLは http://<Server Name>/api/v2/ です（ローカル環境の例: http://localhost:8080/api/v2 ）。

注釈

お気に入り機能を利用するには、 user.favorite 設定が有効である必要があります。

お気に入りドキュメント一覧の取得

リクエスト

HTTPメソッド GET
エンドポイント /api/v2/favorites

query_id で識別される検索結果のうち、呼び出しユーザーが過去にお気に入り登録したドキュメントの ID を返します。 query_id は検索 API （ /search ）が返す不透明な識別子（ query_id フィールド）です。

匿名の呼び出し元（セッションに紐づくユーザーコードがない場合）は auth_required (401) になります。 user.favorite 機能が無効のときは invalid_request (400) になります。 query_id がセッション内のキャッシュされた結果セットに一致しないときは、 200 と空の data 配列を返します。

リクエストパラメーター

リクエストパラメーター
query_id 検索 API （ /search ）が返す不透明な query_id （query, 必須, str）。

表: リクエストパラメーター

レスポンス

成功時（200）は、共通エンベロープの response 直下に以下のフィールドが返ります。

{
  "response": {
    "status": 0,
    "record_count": 2,
    "data": [
      { "doc_id": "a1b2c3d4e5f6" },
      { "doc_id": "f6e5d4c3b2a1" }
    ]
  }
}

各フィールドについては以下の通りです。

レスポンスフィールド
record_count data 内のお気に入りドキュメント数（int）。
data クエリ対象の結果セット中のお気に入りドキュメントを、検索結果の順序を保って返す配列。各要素は {doc_id} 。

表: レスポンスフィールド

エラーレスポンス

エラーモデルの詳細は APIの概要 を参照してください。このエンドポイントが返す HTTP ステータスは以下の通りです。

エラーレスポンス
ステータスコード 説明
400 Bad Request リクエストが不正な場合（ user.favorite 機能が無効な場合を含む）。
401 Unauthorized 認証が必要な場合（匿名の呼び出し元）。
405 Method Not Allowed HTTP メソッドが許可されていない場合。
500 Internal Server Error サーバー内部エラーが発生した場合。

表: エラーレスポンス

お気に入り状態の取得

リクエスト

HTTPメソッド GET
エンドポイント /api/v2/documents/{docId}/favorite

指定したドキュメントのお気に入り状態を取得します。

リクエストパラメーター

リクエストパラメーター
docId ドキュメント識別子（path, 必須, パターン ^[A-Za-z0-9_-]+$ ）。

表: リクエストパラメーター

レスポンス

成功時（200）は、共通エンベロープの response 直下に以下のフィールドが返ります。

{
  "response": {
    "status": 0,
    "doc_id": "a1b2c3d4e5f6",
    "favorite": true,
    "count": 5
  }
}

各フィールドについては以下の通りです。

レスポンスフィールド
doc_id ドキュメント ID（str）。
favorite 呼び出しユーザーのお気に入りかどうか（bool）。
count このドキュメントのお気に入り数（int64）。

表: レスポンスフィールド

エラーレスポンス

エラーモデルの詳細は APIの概要 を参照してください。このエンドポイントが返す HTTP ステータスは以下の通りです。

エラーレスポンス
ステータスコード 説明
400 Bad Request リクエストが不正な場合。
404 Not Found リソースが見つからない場合。
405 Method Not Allowed HTTP メソッドが許可されていない場合。
500 Internal Server Error サーバー内部エラーが発生した場合。

表: エラーレスポンス

お気に入りの登録

リクエスト

HTTPメソッド POST
エンドポイント /api/v2/documents/{docId}/favorite

指定したドキュメントをお気に入りに登録します。 状態を変更するリクエストのため、 X-Fess-CSRF-Token ヘッダーが必要です（ APIの概要 を参照）。

リクエストパラメーター

リクエストパラメーター
docId ドキュメント識別子（path, 必須, パターン ^[A-Za-z0-9_-]+$ ）。

表: リクエストパラメーター

リクエストボディ

Content-Type: application/json で、以下のフィールドを持つ JSON （FavoritePostRequest）を送信します。

{
  "query_id": "f8b1c2d3e4a5"
}
リクエストボディ
query_id 検索 API （ /search ）が返す不透明な query_id （str, 必須）。

表: リクエストボディ

レスポンス

成功時（200）は、共通エンベロープの response 直下に以下のフィールドが返ります。

{
  "response": {
    "status": 0,
    "doc_id": "a1b2c3d4e5f6",
    "ok": true,
    "favorite": true,
    "count": 6,
    "already_existed": false
  }
}

各フィールドについては以下の通りです。

レスポンスフィールド
doc_id ドキュメント ID（str）。
ok 常に true （bool）。
favorite 常に true （bool）。新規追加でも既存でも、ドキュメントは呼び出しユーザーのお気に入りとなります。
count 操作後の現在のお気に入り数（int64）。新規追加では更新前カウント +1（楽観的）、冪等な再 POST では保存済みカウントを反映します。
already_existed お気に入りが過去に登録済みだった場合 true （bool, 冪等な再 POST）。お気に入りを新規登録した最初の POST では存在しません。

表: レスポンスフィールド

エラーレスポンス

エラーモデルの詳細は APIの概要 を参照してください。このエンドポイントが返す HTTP ステータスは以下の通りです。

エラーレスポンス
ステータスコード 説明
400 Bad Request リクエストが不正な場合。
401 Unauthorized 認証が必要な場合。
403 Forbidden CSRF トークンの欠落・失効などで許可されない場合。
404 Not Found リソースが見つからない場合。
405 Method Not Allowed HTTP メソッドが許可されていない場合。
413 Payload Too Large リクエストボディがサイズ上限を超えている場合。
415 Unsupported Media Type サポートされていない Content-Type の場合。
500 Internal Server Error サーバー内部エラーが発生した場合。

表: エラーレスポンス