1. 各エンドポイントの概要・用途（ユースケース）

フロントエンドの実装を行う際、どのAPIをどのような画面仕様やユースケースでコールすべきかを整理した「逆引き一覧ガイド」です。

エンドポイント別ユースケース早見表

2. 開発の共通基本事項

① API接続先環境

• 本番環境 (Production): https://api.contents.01core.app
• βテスト環境 (Beta): https://api.contents.beta.01core.dev

② 認証仕様について

本 API は、OpenAPI（YAML仕様書）上各エンドポイントに security: [] が明示されている通り、認証不要（公開API）です。フロントエンドからの通信時、Authorization ヘッダーを付与する必要はありません。

③【最重要】パラメータの命名規則（Casing）

バックエンドはパラメータ名の大文字・小文字を厳密にバリデーションします。ここを誤ると「パラメータが無視される」または「400 Bad Request」となります。

• パスパラメータ (Path Parameters): camelCase（小文字開始）
  • 例: contractId, apiendpoint, contentId
• クエリパラメータ (Query Parameters): PascalCase（大文字開始）
  • 例: PerPage, Page, FullTextQuery, Filter, Sort, Operator

3. 各API仕様

【1】モデル定義取得 API

コンテンツモデルのフィールド定義、型、および検索に使える比較演算子のメタデータを取得するAPIです。動的なフィルタUIや入力フォームの自動構築に利用します。

• HTTP メソッド: GET
• パス: /v2/{contractId}/{apiendpoint}/definition

① レスポンス（200 OK）サンプル

{
  "ID": "00000000-0000-0000-0000-000000000000",
  "ApiName": "【サンプル】お知らせ・FAQマスタ",
  "Fields": [
    {
      "ID": "11111111-1111-1111-1111-111111111111",
      "FieldType": "Text",
      "FieldName": "タイトル",
      "FieldID": "Title",
      "Sortable": true,
      "EnableAggregate": false,
      "Description": "コンテンツの主要な表示タイトルです。",
      "Reference": {
        "ApiEndpoint": "",
        "FieldID": ""
      },
      "ValidFilterOperators": [
        "equals"
      ]
    },
    {
      "ID": "22222222-2222-2222-2222-222222222222",
      "FieldType": "MultiReference",
      "FieldName": "カテゴリ一覧",
      "FieldID": "CategoryList",
      "Sortable": false,
      "EnableAggregate": true,
      "Description": "関連する製品やサポートカテゴリのバインド情報（複数可）。",
      "Reference": {
        "ApiEndpoint": "categories_endpoint",
        "FieldID": "11111111-1111-1111-1111-111111111111"
      },
      "ValidFilterOperators": [
        "all_of",
        "any_of"
      ]
    },
    {
      "ID": "33333333-3333-3333-3333-333333333333",
      "FieldType": "Checkbox",
      "FieldName": "ステータスタグ",
      "FieldID": "StatusTag",
      "Sortable": false,
      "EnableAggregate": false,
      "Description": "NEWやSALEなどのフラグタグ情報。",
      "Items": [
        {
          "ID": "44444444-4444-4444-4444-444444444444",
          "Label": "NEW"
        }
      ],
      "Reference": {
        "ApiEndpoint": "",
        "FieldID": ""
      },
      "ValidFilterOperators": [
        "all_of",
        "any_of"
      ]
    }
  ]
}

② スキーマ名と本ガイドにおける呼称の対応表

③ スキーマ＆データ構造・検索演算子 早見表

モデル定義取得API（/definition）から返却される Fields 配列内の各フィールドのデータ構造定義、およびそれに応じたフロントエンドでのUI・検索フォームの動的構築方針の一覧です。

【2】コンテンツ詳細取得 API

特定のUUIDを指定して、1件のコンテンツ詳細データを取得します。詳細ページや、CMSから発行されるプレビューキー（PreviewKey）を利用した「下書き・非公開コンテンツのライブプレビュー」機能の構築に利用します。

• HTTP メソッド: GET
• パス: /v2/{contractId}/{apiendpoint}/{contentId}
• プレビューヘッダー: PreviewKey: [UUID] (任意)

① レスポンス（200 OK）サンプル

{
  "UUID": "55555555-5555-5555-5555-555555555555",
  "ID": "sample-content-id-001",
  "CreatedAt": "2026-08-25T03:00:00Z",
  "UpdatedAt": "2026-08-25T05:00:00Z",
  "FieldValues": {
    "Title": "【サンプル】よくあるタイトルのタイトル（ここにプレーンテキストのタイトル・お知らせタイトルが入ります）",
    "Answer": "【サンプル】タイトルに対する簡易的な回答テキストです。プレーンテキストなので、シンプルなバインド描画に適しています。",
    "AnswerDetail": "<div class=\"paragraph\">【サンプル】リッチテキストエディタで作成されたHTMLフォーマットの回答です。<br/>フロントエンドでは安全な手段を用いてパース・描画してください。</div>",
    "StatusTag": ["NEW"],
    "CategoryList": [
      {
        "ApiEndpoint": "categories_endpoint",
        "ID": "66666666-6666-6666-6666-666666666666",
        "DisplayValue": "カテゴリA"
      }
    ],
    "Date": "2026-08-25"
  }
}

② スキーマ名と本ガイドにおける呼称の対応表

③ スキーマ＆データ構造 早見表

詳細取得時に返却される FieldValues 内の各フィールドデータ構造とフロントエンドでの処理・レンダリング方針です。

【3】コンテンツ検索 API

条件にヒットするコンテンツ一覧の取得、全文キーワード検索、精密なフィルタリング、ページネーション、ソート順の制御を行う、一覧表示画面の主役となるAPIです。

• HTTP メソッド: GET
• パス: /v2/{contractId}/{apiendpoint}/search
• パラメータ: PerPage, Page, FullTextQuery, Filter, Sort, Operator

① レスポンス（200 OK）サンプル

{
  "TotalCount": 25,
  "PerPage": 10,
  "Page": 0,
  "Contents": [
    {
      "UUID": "77777777-7777-7777-7777-777777777777",
      "ID": "sample-content-id-002",
      "CreatedAt": "2026-07-27T09:00:00Z",
      "UpdatedAt": "2026-07-27T09:00:00Z",
      "FieldValues": {
        "Title": "【サンプル】初期ログイン方法について教えてください。",
        "Answer": "【サンプル】登録確認メールに記載された仮パスワードを使用し、ログインした上でプロフィールの設定を行ってください。",
        "CategoryList": [
          {
            "ApiEndpoint": "categories_endpoint",
            "ID": "88888888-8888-8888-8888-888888888888",
            "DisplayValue": "初期サポート"
          }
        ]
      }
    }
  ]
}

② スキーマ名と本ガイドにおける呼称の対応表

③ スキーマ＆データ構造・検索演算子 早見表

検索リクエストのクエリ（Filter）を構築する際、指定した FieldID に対して利用可能な比較演算子、および送信すべき検索値（Value / Values / Range）の具体的なデータ構造です。

④ 全文検索（FullTextQuery）仕様

キーワード入力によるコンテンツ全体の横断的な曖昧検索（全文検索）を処理するパラメータです。

• 除外検索のサポート (exclude):
  FullTextQuery の Operator には、通常の曖昧検索を表す fuzzy_match の他に、指定したキーワードを検索対象から除外する exclude も指定可能です。

  {
    "Keywords": "広告 キャンペーン",
    "Operator": "exclude"
  }

• 全文検索インデックスの有効化条件:
  FullTextQuery による検索（部分一致やキーワードマッチ）を有効にするためには、管理画面のコンテンツモデルのフィールド詳細設定で「全文検索対象」を「する」に設定しておく必要があります。
• 挙動とフィルタ制限のクリア:
  • 管理画面で「全文検索対象」を「する」に設定したフィールドのみが、バックエンドの検索エンジンにおいて逆インデックス（全文検索用インデックス）の対象として処理されます。
  • 「しない」に設定されているフィールドは、たとえテキスト（Text, Textarea, Editor）型であっても FullTextQuery の検索キーワードのマッチング対象から完全に除外されます。
  • 詳細フィルタ（Filter）をサポートしていないテキストエリア（Textarea）やリッチエディタ（Editor）は、この「全文検索対象」を「する」に設定して FullTextQuery で検索を受け付けるのが原則的な仕様となります。

⑤ ページネーション（TotalCount, PerPage, Page）仕様

検索結果レスポンスの一番外側（インライン定義 (Response)）に含まれる、ページネーション表示と制御を実装するための必須メタデータ群です。

• 各メタデータの定義:
  • TotalCount (Integer): 検索条件（Filter や FullTextQuery）に合致する、データベース内の該当コンテンツの「総件数」です。
  • PerPage (Integer): 1ページあたりに取得する最大件数です。省略時のデフォルト値は 20、1リクエストあたりの最大取得制限値は 100 です。リクエスト時に送信した PerPage の値がそのままレスポンスでも現在の適用値として返却されます。
  • Page (Integer): 現在取得しているページ位置（0から始まるインデックス：0-based）です。リクエスト時に送信した Page の値がそのまま返却されます。
• フロントエンド実装時の活用方針:
  • 総ページ数（TotalPages）の計算:
    画面上に「全〇ページ」を表示するための総ページ数は、以下の計算式で動的に算出します。
    TotalPages = Math.ceil(TotalCount / PerPage)
  • UI表示（1始まり）とAPI（0始まり）の相互変換:
    APIは Page=0 を1ページ目として処理するため、フロントエンドのUI上の表示（ページ1, ページ2...）と連動させる際は、APIリクエスト時に必ず UIの表示ページ数 - 1 を行い、レスポンス描画時には Page + 1 を行って画面にバインドします。
  • 「前へ」「次へ」ボタンの活性/非活性制御:
    • 「前へ（Previous）」ボタンの有効条件: Page > 0
    • 「次へ（Next）」ボタンの有効条件: Page < (TotalPages - 1)

【4】コンテンツ集計 API

指定した条件（Filter / FullTextQuery）に一致するコンテンツについて、フィールドの値ごとの件数を集計して返します。絞り込みUIで「東京都 (12)」のように件数を出したい場合などに使用します。

• HTTP メソッド: GET
• パス: /v2/{contractId}/{apiendpoint}/aggs
• パラメータ: FullTextQuery, Filter, Operator
  • FullTextQuery / Filter / Operator は、コンテンツ検索APIと同じ形式・同じ渡し方（JSON文字列をURLエンコード）です。
• 集計仕様:
  • 集計対象: EnableAggregate: true のフィールドのみ（モデル定義取得APIで確認）。
    ※集計を実行するためには、管理画面のコンテンツモデルのフィールド詳細設定で「集約対象」を「する」に設定しておく必要があります。これによってAPIレスポンス上で EnableAggregate: true となり、集計可能になります。設定が「しない」（EnableAggregate: false）になっているフィールドは集計対象外となり、レスポンスの Result には含まれません。
  • 取得上限: 1フィールドあたり上位100件（※ただし、日時フィールドは上限なし）

① レスポンス（200 OK）サンプル

{
  "Result": {
    "CategoryList": {
      "66666666-6666-6666-6666-666666666666": 32,
      "88888888-8888-8888-8888-888888888888": 25,
      "99999999-9999-9999-9999-999999999999": 14
    }
  }
}

② スキーマ名と本ガイドにおける呼称の対応表

③ スキーマ＆データ構造・集計仕様 早見表

集計APIから返却される集計結果（Result）のデータ型ごとの集計仕様およびフロントエンドでの描画方針です。

【5】カウント API (Count Update)

特定のコンテンツ内の、指定された Counter（カウンター）型フィールドの数値をリアルタイムに更新（加算または減算）します。記事の「いいね！」数、お気に入り登録数、簡易的なページビュー数の加減算など、バックエンド側の中介サーバーを介さずにフロントエンドから直接カウンターを増減させるユースケースに最適です。

• HTTP メソッド: POST
• パス: /v2/{contractId}/{apiendpoint}/{contentId}/{fieldId}/count
• パラメータ（Path Parameters）:
  • contractId (Path / UUID) : 契約ID (必須)
  • apiendpoint (Path / String) : 対象のAPIエンドポイント名 (必須)
  • contentId (Path / String) : 対象コンテンツのID (IDAlias または UUID) (必須)
  • fieldId (Path / String) : カウンター値を加算・減算したい Counter 型フィールドのID (必須)
• リクエストボディ (Required):
  • コンテンツタイプ: application/json
  • データ構造:

    {
      "Value": 1
    }

    • Value (Integer / 必須): 加算または減算する数値。正の整数（例：1）を指定した場合は加算（インクリメント）、負の整数（例：-1）を指定した場合は減算（デクリメント）となります。
• レスポンス（200 OK）:
  加算・減算処理が適用された後の「カウンター」フィールド情報が以下のJSON構造で返却されます。

  {
    "Prefix": "",
    "Suffix": "回",
    "Value": 124
  }

  • Prefix (String / 必須): 管理画面で設定された接頭辞
  • Suffix (String / 必須): 管理画面で設定された接尾辞
  • Value (Integer / 必須): 加算・減算処理適用後の最終カウンター数値
• エラーレスポンス ＆ 例外処理:
  • 400 Bad Request: リクエスト内容が不適切、または必須項目が不足しています。
    • contractId / apiendpoint / contentId / fieldId が未指定の場合（message: "'[parameter]' is required."）。
    • 加算する数値（Value）がリクエストボディに指定されていない、または整数以外の不正なデータ型が送信された場合（error.message: "ValidationErrors", field: "Value"）。
    • リクエストボディ自体が不適切な場合（message: "Invalid request body."）。
  • 404 Not Found:
    • 指定されたコンテンツが存在しない場合（message: "NOT_FOUND"）。
    • 指定されたフィールドが存在しない、あるいはそのフィールドが Counter タイプではない場合（message: "'fieldId' is not found."）。
  • 409 Conflict:
    • カウント更新後の最終数値がシステム上限値（20億）を超える、または下限値（-20億。管理画面で「負数を許可しない」設定の場合は0）を下回る場合（message: "'fieldId' value exceeds the count limit or is below the minimum."）。
  • 500 Internal Server Error:
    • サーバー側で予期せぬエラーが発生した場合（message: "An unexpected error has occurred"）。
  • 503 Service Unavailable:
    • 同時多発的なカウント処理集中などにより、一時的にリソース不足が発生した場合（message: "A temporary error has occurred, Please try again."）。
• 挙動とセキュリティ設計:
  本 API は公開用（認証不要）としてフロントエンドから直接コールできるように設計されていますが、同一クライアントからの連続F5連打多重投稿や自動ボットによる過剰な不正リクエスト（スパム行為）から保護するため、API Gatewayレイヤーにおいて自動的にレートリミット（流量制限）が適用されます。 確実な保護のため、フロントエンドUIでもボタンのデバウンス（多重クリック防止）や通信中の非活性化（disabled）処理を併せて実装することを推奨します。

4. 開発者向けガイドライン

① コンテンツのFieldTypeとデータ構造の対応表

標準JavaScript（ES6+）での開発において、エディタ（VS Code等）のコード補完・入力を自動有効化する JSDocアノテーション、および返却された複雑なデータ構造を画面に美しく出力するための実用処理ユーティリティ（バニラJS）です。

// ── 1. JSDoc型定義（VS Code等の入力補完を自動有効化します） ──

/**
 * @typedef {Object} NumberStructure
 * @property {string} Prefix - 接頭辞 (例: "¥")
 * @property {string} Suffix - 接尾辞 (例: "（税込）")
 * @property {number} Value - 数値
 */

/**
 * @typedef {Object} PictureStructure
 * @property {string} URL - 画像のアセットURL
 * @property {string} Alt - 代替テキスト
 * @property {string} Caption - 画像キャプション
 */

/**
 * @typedef {Object} AddressStructure
 * @property {string} ZipCode - 郵便番号 (ハイフンあり)
 * @property {string} Prefecture - 都道府県
 * @property {string} Municipality - 市区町村
 * @property {string} StreetNumber - 番地
 * @property {string} BuildingName - ビル・マンション名 (任意)
 */

/**
 * @typedef {Object} ReferenceStructure
 * @property {string} ApiEndpoint - 参照先APIエンドポイント
 * @property {string} ID - 参照データのUUID
 * @property {string} DisplayValue - 参照データ側の表示用名称
 */

// ── 2. JavaScript実用フォーマッター（そのままコピーしてUIコンポーネントで使えます） ──

/**
 * 住所オブジェクト（AddressStructure）を1つの読みやすい文字列に結合します
 * @param {AddressStructure} address
 * @returns {string} 結合された住所文字列
 */
export function formatAddress(address) {
  if (!address) return '';
  const { ZipCode, Prefecture, Municipality, StreetNumber, BuildingName } = address;
  const mainAddress = `${Prefecture || ''}${Municipality || ''}${StreetNumber || ''}`;
  const bName = BuildingName ? ` ${BuildingName}` : '';
  return ZipCode ? `〒${ZipCode} ${mainAddress}${bName}` : `${mainAddress}${bName}`;
}

/**
 * 金額や数値（NumberStructure）をカンマ区切りし、接頭辞・接尾辞を付与して整形します
 * @param {NumberStructure} numObj
 * @returns {string} フォーマットされた金額表示（例: "¥1,500（税込）"）
 */
export function formatCurrency(numObj) {
  if (!numObj || numObj.Value === undefined) return '';
  // 日本の3桁区切り（カンマ）フォーマッター
  const formattedValue = new Intl.NumberFormat('ja-JP').format(numObj.Value);
  return `${numObj.Prefix || ''}${formattedValue}${numObj.Suffix || ''}`;
}

/**
 * HTMLタグ（Editor型など）からプレーンテキストを安全に抽出します（文字数制限等に便利）
 * @param {string} htmlString
 * @returns {string} タグが除去されたプレーンテキスト
 */
export function stripHtmlTags(htmlString) {
  if (!htmlString) return '';
  return htmlString.replace(/<\/?[^>]+(>|$)/g, "");
}

② コンテンツ検索クエリ構築とページネーションの完全設計

コンテンツ検索 API (/v2/.../search) で、高度な一覧画面を完璧に構築するための設計書です。

【最重要】JSONオブジェクトのシリアライズとURLエンコード

クエリパラメータ（FullTextQuery, Filter, Sort）は、すべて複雑な入れ子構造のJSONオブジェクトです。これらをHTTP GETリクエストのクエリパラメータとして安全に送信するためには、以下の2ステップの処理が必須となります。

1. JSON文字列化（シリアライズ）: JavaScriptの JSON.stringify(object) を用いて、オブジェクトをJSON形式のテキスト文字列に変換します。
2. URLエンコード（URIエンコード）: encodeURIComponent(jsonString) や URLSearchParams などの標準ユーティリティを使用して、必ずURLセーフな文字列（パーセントエンコーディング形式）に変換します。

1. ページネーション（PerPage / Page）のパラメータ制御

一覧表示件数の制限と取得するページ位置の指定には、PerPage と Page クエリパラメータを使用します。PerPage パラメータを省略、または未指定（null）にした場合のデフォルトの表示件数は 20 件、1リクエストあたりの最大取得制限値は 100 件です。

インデックスは「0（ゼロ）始まり」
バックエンドの仕様上、ページ番号を示す Page パメータは 0始まり（0-based index） です。フロントエンドのUI（1ページ目、2ページ目...）と連動させる際は、必ず -1の変換処理 を行ってリクエストを送信してください。

リクエストクエリの対比 (1ページあたり10件表示の場合)

• 【UI上の第 1 ページ】を表示する場合: GET /v2/{contractId}/{apiendpoint}/search?PerPage=10&Page=0
• 【UI上の第 2 ページ】を表示する場合: GET /v2/{contractId}/{apiendpoint}/search?PerPage=10&Page=1

2. 全文検索 (FullTextQuery) のJSON構造

モデル内の「全文検索対象: する」に設定されたすべてのテキスト系フィールドを対象に、スペース区切りのキーワード群で曖昧検索を行います。
※管理画面での「全文検索対象」の設定状況は、APIの内部検索インデックスに直結します。

{
  "Keywords": "ログイン 二要素認証",
  "Operator": "fuzzy_match"
}

3. 詳細フィルタリング (Filter) のOperator別JSON構造例

フィルタをかける際は、論理結合を表すトップレベルの Operator（and または or）の中に、Conditions という配列を持ちます。その各要素の中で、比較演算子（Operator）を使い分けます。

A. equals (完全一致演算子) の構造例
テキストの完全一致、Toggle型の真偽値一致、UUID/IDの完全一致で使用します。

・例: 有効（ON）かつ特定のカテゴリID（UUID）を持つコンテンツを抽出する条件

{
  "Operator": "and",
  "Conditions": [
    {
      "FieldID": "StatusToggle",
      "Operator": "equals",
      "Value": true
    },
    {
      "FieldID": "CategoryList",
      "Operator": "any_of",
      "Values": ["66666666-6666-6666-6666-666666666666"]
    }
  ]
}

・ポイント: Toggle型のフィールドにマッチさせる Value には、文字列の "true" ではなくBooleanの true / false を渡します。また、UUID や ID 型も同様に equals で完全一致指定できます。

B. any_of / all_of (配列一致演算子) の構造例
チェックボックスやマルチ参照、ドロップダウンなど、「選択されたいずれか（またはすべて）」に一致させる場合に使用します。

・例: 「ステータスタグ」のいずれか（複数可）に一致するコンテンツを抽出する条件

{
  "Operator": "and",
  "Conditions": [
    {
      "FieldID": "StatusTag",
      "Operator": "any_of",
      "Values": [
        "status_tag_uuid_0001",
        "status_tag_uuid_0002"
      ]
    }
  ]
}

・ポイント: 検索キーワードや単一値の Value ではなく、Values という複数形（Stringの配列）をキーとして値を指定する必要があります。

C. between (範囲指定演算子) の構造例
数値や日付・日時の範囲を指定して絞り込む場合に使用します。

・例: 価格が 1,000円から5,000円 の範囲のコンテンツを抽出する条件

{
  "Operator": "and",
  "Conditions": [
    {
      "FieldID": "Price",
      "Operator": "between",
      "Range": {
        "Min": 1000,
        "Max": 5000
      }
    }
  ]
}

・ポイント: 単一の値ではなく、Range オブジェクトを指定し、その中に Min と Max という境界となるキーをセットします。

4. ソート順の制御 (Sort) のJSON構造

表示順の並び替え条件を、優先度順に配列形式で指定します。

[
  { "Key": "CreatedAt", "Order": "desc" },
  { "Key": "SortOrder", "Order": "asc" }
]

ソート（Sort）パラメータ未指定時のデフォルト挙動
APIリクエスト時に Sort パラメータを省略、または未指定（null）にした場合、バックエンド側では自動的に以下の優先順位でデフォルトのソートロジックが適用されます。

1. FullTextQuery または Filter のいずれかが指定されている場合:
   • 関連度（Relevance）順の降順で自動的にソートされます。キーワードのマッチ度やフィルタへの合致度が高いコンテンツが優先的に上位に表示されます。
2. FullTextQuery と Filter の双方が未指定（全件取得など）の場合:
   • 第一ソートキー: UpdatedAt の降順（最終更新日時が新しい順）
   • 第二ソートキー: ID の昇順
   • これにより、「最近更新されたコンテンツから順に並び、同一日時の場合はID順」に並ぶことが保証されます。

フロントエンド側で明示的な並び替えUI（例：「価格が安い順」など）を提供しないデフォルト表示時においては、この暗黙の優先挙動を前提にして一覧レイアウトを設計・確認することが可能です。

5. フロントエンド（JavaScript / fetch）での一覧・ページネーション実装例

外部ライブラリに依存せず、ブラウザ標準の fetchAPI を用いてパラメータを安全にエンコード・シリアライズし、非同期通信（async/await）で一覧データを取得する、そのままコピー＆ペーストして使える堅牢な実用コード例です。

/**
 * ページ指定によるコンテンツ検索一覧の取得 (fetch API 最終決定版)
 * @param {number} pageUi - UI上でユーザーがクリックしたページ番号 (1, 2, 3...)
 * @param {number} perPage - 1ページあたりの表示件数
 * @param {string} categoryUuid - 絞り込みたいカテゴリのUUID (任意)
 * @returns {Promise<Object>} APIから返却されたJSONデータ
 */
async function fetchContentsList(pageUi = 1, perPage = 10, categoryUuid = null) {
  // ① UI上のページ番号（1始まり）を、APIの仕様（0始まり）に変換
  const apiPage = pageUi - 1;

  // ② 詳細フィルタのオブジェクト構築
  const filterConditions = [];
  if (categoryUuid) {
    filterConditions.push({
      FieldID: "CategoryList",
      Operator: "any_of", // MultiReference は equals 非対応のため any_of を使用
      Values: [categoryUuid] // 複数一致条件（配列形式）で指定します
    });
  }

  const filterObj = {
    Operator: "and",
    Conditions: filterConditions
  };

  const sortObj = [{ Key: "CreatedAt", Order: "desc" }];

  // ③ パラメータの組み立て
  // ※ URLSearchParamsに渡す各パラメータオブジェクトは、必ず事前に JSON.stringify() でシリアライズします。
  // ※ URLSearchParamsはブラウザ標準仕様で、これらを自動的かつ安全にURLエンコード（百分率エンコーディング）します。
  const params = new URLSearchParams({
    PerPage: perPage.toString(),
    Page: apiPage.toString(),
    Sort: JSON.stringify(sortObj)
  });

  if (filterConditions.length > 0) {
    params.append('Filter', JSON.stringify(filterObj));
  }

  const contractId = "YOUR_CONTRACT_ID";
  const apiendpoint = "sample_endpoint";
  const url = `https://api.contents.01core.app/v2/${contractId}/${apiendpoint}/search?${params.toString()}`;

  try {
    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'Accept': 'application/json'
      }
    });

    if (!response.ok) {
      // 400 Validation Errorや401, 404などのエラーハンドリング
      const errorData = await response.json().catch(() => ({}));
      throw new Error(errorData.message || `HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    // 返却データ構造: { TotalCount: 13, PerPage: 10, Page: 0, Contents: [...] }
    return data;
  } catch (error) {
    console.error('API一覧取得に失敗しました:', error.message);
    throw error;
  }
}

// ── ページネーションUI制御ロジックの計算例 ──
function calculatePaginationState(totalCount, perPage, apiPage) {
  const totalPages = Math.ceil(totalCount / perPage);
  const currentPageUi = apiPage + 1; // 0始まりから1始まりに変換
  const hasPrevious = apiPage > 0;
  const hasNext = apiPage < (totalPages - 1);

  return { totalPages, currentPageUi, hasPrevious, hasNext };
}

6. よくあるトラブルとQ&A（Troubleshooting）