公開API

公開APIは、公開中のコンテンツ・コレクションを認証なしで読み取るための読み取り専用APIです。返すのは「公開」した版の公開項目だけで、下書きや非公開項目は含まれません。ブラウザからは登録済みの接続元（Origin）からのみ読み込めます。通常は CMS SDK から利用しますが、直接呼び出すこともできます。

エンドポイント

GET https://cms.magichtml.dev/api/public/v1/sites/{site}/resources/{key}

APIトークンやログインは不要です。管理APIのトークンを公開サイトに埋め込まないでください。

curl 'https://cms.magichtml.dev/api/public/v1/sites/SITE_ID/resources/news?page=1&per_page=10'

レスポンス

{
  "version": "9d3f2c1e-5b7a-4c2e-8f10-2a6b7c8d9e0f",
  "name": "お知らせ",
  "kind": "collection",
  "fields": [
    {"key": "title", "label": "タイトル", "type": "text", "required": true, "public": true},
    {"key": "body", "label": "本文", "type": "textarea", "required": false, "public": true}
  ],
  "records": [
    {"key": "news-002", "values": {"body": "新しいサービスを開始しました。", "title": "サービス開始のお知らせ"}},
    {"key": "news-001", "values": {"body": "営業時間を変更します。", "title": "営業時間変更"}}
  ],
  "pagination": {"page": 1, "per_page": 30, "total": 2}
}

• レコードは並び順の小さい順（同じなら識別キー順）に並びます。
• コンテンツはレコードが1件（識別キー main）なので、records[0].values で値を取り出せます。
• 値の形は項目の型によって異なります（数値は数値、はい／いいえは true／false、リンクは {"url": "..."}、それ以外は文字列）。値を保存していない任意項目は values に含まれないか null になります。詳しくは コンテンツとコレクション をご覧ください。

クエリパラメーター

• 絞り込みは q、entry の順に行われ、その結果に対してページ分けが行われます。pagination.total は絞り込み後の件数です。
• 範囲外のページを指定すると、records は空配列になります。
• これらのパラメーターはコンテンツにも使えますが、主にコレクションの一覧・詳細表示で使います。

# 「採用」を含むお知らせの2ページ目（1ページ10件）
curl 'https://cms.magichtml.dev/api/public/v1/sites/SITE_ID/resources/news?q=採用&page=2&per_page=10'

# 識別キー news-001 のお知らせ1件
curl 'https://cms.magichtml.dev/api/public/v1/sites/SITE_ID/resources/news?entry=news-001'

非公開項目の扱い

「公開」をオフにした項目は、レスポンスを作る前に取り除かれます。

• fields に定義が含まれず、records[].values に値も含まれません。
• 検索（q）は非公開項目を除いた値に対して行われるため、非公開項目の内容で検索しても一致しません。
• 公開・非公開の設定は公開版ごとに記録されています。設定を変えたら再度公開してください。

CORS と接続元（Origin）

ブラウザ上の JavaScript から読み込む場合、そのページのオリジンをサイトの「許可する接続元」に登録する必要があります。

• サイト画面の「サイト設定・接続元」に、1行に1件ずつ入力します（例：https://example.com）。
• http:// または https:// で始まり、パス・クエリ・#・ユーザー名を含まない形式で入力します。末尾の / は自動で取り除かれます。
• ワイルドカード（*）は使えません。最大20件です。
• ブラウザが送る Origin と完全に一致する必要があります。https://example.com と https://www.example.com、ポート番号の有無は別の接続元として扱われます。

許可されるメソッドは GET と OPTIONS、リクエストヘッダーは Content-Type と Accept です。Cookie などの資格情報は使いません。

エラー

エラー時は JSON の message を含むレスポンスを返します。

リクエスト数の上限

公開APIは、送信元IPアドレスごとに 1分あたり120リクエスト までです。超えると 429 を返します。ページを表示するたびに同じリソースを何度も読み込まないよう、1ページ内での呼び出しはまとめてください。

キャッシュ

公開APIのレスポンスには Cache-Control: no-store が付きます。ブラウザや中継サーバーにキャッシュされないため、公開・公開停止・版の切り替えは次のリクエストからすぐに反映されます。

関連ページ

• CMS SDK
• コンテンツとコレクション