Fessのv2 APIを自作クライアントから呼ぶとき、正しいJSONでも本文の最上位が配列やnullだと受け付けられません。JSON本文の検証修正と、実際の応答に合わせたOpenAPI・リファレンスの訂正をまとめて確認します。
JSON本文はUTF-8のオブジェクトにする
ログイン、クリック記録、パスワード変更、タグ、お気に入り、チャットなど、共通のJSON本文読み込みを使うAPIが対象です。Content-Type: application/jsonを指定し、文字コードを明示する場合もUTF-8を使います。
修正後は最上位のnull、配列、文字列、数値、真偽値をHTTP 400、invalid_requestとして拒否します。オブジェクト内のnull、たとえば{"a":null}はJSONの構造として読み取れますが、各APIの必須項目の検証は別に実行されます。
不正なUTF-8バイト列も400になります。以前のように代替文字へ置き換えてタグ名などを保存しません。先頭のUTF-8 BOMは読み取り時に除去します。0バイトの本文は空オブジェクト相当として読み取る仕様を維持し、空白だけの本文や未入力の必須フィールドまで成功とするものではありません。
この検証を有効にする設定は追加していません。各APIの認証、CSRF、本文サイズ制限は従来の条件に従い、サイズ上限は呼び出すAPIで決まります。400では本文を修正し、文字コードやContent-Typeによる415、サイズによる413とは区別して扱います。
生成クライアントの数値型を確認する
検索ヒットのcontent_lengthとboostは、クローラーが保存した文書では"9894"、"1.0"のような文字列です。OpenAPIで整数・数値とされていた定義を文字列へ訂正しました。管理用documents APIから登録した文書ではJSON数値を持つ場合もあるため、実データを確認し、必要ならクライアント側で両形式を扱います。
検索語がない場合のhighlight_paramsはnullになり得ます。更新された定義からクライアントを再生成し、検索語なしの応答もデシリアライズできるか確認してください。定義上の型が変わっても、サーバーがここで既存文書を変換するわけではありません。
UI設定と認証エラーにも対応する
/api/v2/ui/configのfeatures.login_linkは真偽値だけでなく、SSO利用時には相対URLの"sso/"になる場合があります。default_label_valuesやdefault_sortは画面の初期選択用で、/api/v2/searchが自動適用する値ではありません。
サジェストのnumの初期値は10で、page_sizeは実際に返された語数です。語数が要求より少なくても異常と決め付けないでください。各APIはログイン必須設定や無効なトークンなどの条件で401を返し、デコード不能なクエリ文字列では処理前に400になり得ます。
実環境に近い検索文書、検索語なし、認証失敗、SSO設定の組み合わせでクライアントを確認すると、正常系だけでは見つからない型の不一致を減らせます。