お気に入り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

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

匿名（未認証）の呼び出し元もこのエンドポイントを利用できます。その場合、 favorite は false を返しますが、 count には保存されているお気に入り数がそのまま返されます（このため、このエンドポイントは 401 を返しません）。 お気に入り機能（ user.favorite ）が無効な場合は invalid_request (400) になります。

リクエストパラメーター

リクエストパラメーター
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の概要 を参照）。 また、呼び出しユーザーが認証されている必要があります。匿名の呼び出し元は auth_required (401) になります。

query_id は、対象ドキュメントが直近の検索結果に含まれることを確認するために使用されます。 query_id がセッション内のキャッシュされた結果セットに一致しない場合は invalid_request (400) 、 docId がその結果セットに含まれない場合は not_found (404) になります。

リクエストパラメーター

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

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

リクエストボディ

Content-Type: application/json （文字コードは UTF-8）で、以下のフィールドを持つ JSON （FavoritePostRequest）を送信します。リクエストボディの最大サイズは 1 KiB（1024 バイト）です。これを超える場合は payload_too_large (413) になります。

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

表: リクエストボディ

レスポンス

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

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

各フィールドについては以下の通りです。上記は新規登録時の例です。お気に入りが過去に登録済みだった（冪等な再 POST の）場合は、これに加えて already_existed フィールド（ true ）が返ります。

レスポンスフィールド
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 サーバー内部エラーが発生した場合。

表: エラーレスポンス