iwa-cms

Appearance

API リファレンス ​

iwa-cms の公開APIを使って、フロントエンドサイトやアプリケーションからコンテンツを取得できます。

認証 ​

すべてのAPIリクエストには、APIキーによる認証が必要です。

ヘッダー ​

X-API-Key: your_api_key_here

APIキーの取得 ​

  1. 管理画面にログイン
  2. サービスを選択
  3. 「APIキー」メニューから新規作成

詳細は APIキー管理 を参照してください。

ベースURL ​

https://your-domain/api/v1

エンドポイント一覧 ​

メソッドパス説明
GET/{endpoint}コンテンツ一覧を取得
GET/{endpoint}/{contentId}コンテンツ詳細を取得
GET/categoriesカテゴリ一覧を取得

endpoint について

{endpoint} にはエンドポイントの パス名（path_name）を指定します。 例: news, blog, products など、管理画面で設定したパス名を使用します。

コンテンツ一覧の取得 ​

公開済みのコンテンツ一覧を取得します。

リクエスト ​

GET /api/v1/{endpoint}

パスパラメータ ​

パラメータ型説明
endpointstringエンドポイントのパス名（例: news, blog）

クエリパラメータ ​

パラメータ型必須説明
filtersstringNoフィルタ条件（例: category[equals]cat123）
limitnumberNo取得件数（デフォルト: 10、最大: 100）
offsetnumberNoオフセット（ページネーション用）

フィルタ構文 ​

microCMS互換のフィルタ構文をサポートしています。

filters=category[equals]カテゴリID

レスポンス ​

json
{
  "contents": [
    {
      "id": "I-ChEjtNOf",
      "endpoint_id": "news",
      "title": "お知らせタイトル",
      "data": {
        "blocks": [
          {
            "id": "block1",
            "type": "heading",
            "content": "見出し",
            "attrs": { "level": 1 }
          },
          {
            "id": "block2",
            "type": "paragraph",
            "content": "本文テキスト"
          },
          {
            "id": "block3",
            "type": "list",
            "content": "リストアイテム",
            "attrs": { "ordered": false }
          }
        ]
      },
      "category_ids": ["cat_123"],
      "published_at": "2025-12-15T12:00:00Z",
      "created_at": "2025-12-14T10:00:00Z",
      "updated_at": "2025-12-15T12:00:00Z"
    }
  ],
  "total_count": 42,
  "limit": 10,
  "offset": 0
}

ブロックタイプ ​

type説明attrs
heading見出しlevel: 1-3
paragraph段落-
listリストordered: true/false
image画像url, alt
codeコードブロックlanguage
tableテーブルrows: string[][]

インラインスタイル

content には <bold>, <italic>, <underline>, <strike> タグが含まれる場合があります。

"content": "通常テキスト<bold>太字</bold>通常"

使用例 ​

bash
# ニュース一覧を取得
curl -H "X-API-Key: your_api_key" \
  https://your-domain/api/v1/news

# カテゴリでフィルタ（5件取得）
curl -H "X-API-Key: your_api_key" \
  "https://your-domain/api/v1/news?filters=category[equals]cat_123&limit=5"

# ページネーション（11件目から10件取得）
curl -H "X-API-Key: your_api_key" \
  "https://your-domain/api/v1/blog?limit=10&offset=10"

コンテンツ詳細の取得 ​

特定のコンテンツを取得します。

リクエスト ​

GET /api/v1/{endpoint}/{contentId}

パスパラメータ ​

パラメータ型説明
endpointstringエンドポイントのパス名
contentIdstringコンテンツID

レスポンス ​

json
{
  "id": "I-ChEjtNOf",
  "endpoint_id": "news",
  "title": "お知らせタイトル",
  "data": {
    "blocks": [
      {
        "id": "block1",
        "type": "heading",
        "content": "見出し",
        "attrs": { "level": 1 }
      },
      {
        "id": "block2",
        "type": "paragraph",
        "content": "本文テキスト"
      }
    ]
  },
  "category_ids": ["cat_123"],
  "published_at": "2025-12-15T12:00:00Z",
  "created_at": "2025-12-14T10:00:00Z",
  "updated_at": "2025-12-15T12:00:00Z"
}

使用例 ​

bash
curl -H "X-API-Key: your_api_key" \
  https://your-domain/api/v1/news/I-ChEjtNOf

カテゴリ一覧の取得 ​

サービスに登録されているカテゴリ一覧を取得します。

リクエスト ​

GET /api/v1/categories

レスポンス ​

json
{
  "categories": [
    {
      "id": "cat_123",
      "name": "重要",
      "created_at": "2025-12-07T10:00:00Z",
      "updated_at": "2025-12-07T10:00:00Z"
    },
    {
      "id": "cat_456",
      "name": "新着",
      "created_at": "2025-12-07T10:00:00Z",
      "updated_at": "2025-12-07T10:00:00Z"
    }
  ]
}

使用例 ​

bash
curl -H "X-API-Key: your_api_key" \
  https://your-domain/api/v1/categories

エラーレスポンス ​

エラー時は以下の形式でレスポンスが返されます。

json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Content not found"
  }
}

エラーコード一覧 ​

HTTPステータスコード説明
400BAD_REQUESTリクエストパラメータが不正
401UNAUTHORIZEDAPIキーが無効または未指定
403FORBIDDENアクセス権限がない
404NOT_FOUNDリソースが見つからない
500INTERNAL_ERRORサーバー内部エラー

SDKとサンプルコード ​

サンプル実装

client-sample/ ディレクトリに、すぐに動かせるサンプル実装があります。

  • index.html - ブラウザ用サンプル（一覧・詳細表示UI付き）
  • api.js - 再利用可能なAPIクライアントクラス
  • example-node.mjs - Node.js用サンプル
bash
# ブラウザで試す
cd client-sample && npx serve .
# http://localhost:3000 で開く

# Node.jsで試す
API_KEY=your-api-key ENDPOINT=news node example-node.mjs

JavaScript / TypeScript ​

typescript
// fetchを使った例
async function getContents(apiKey: string, endpoint: string) {
  const response = await fetch(`https://your-domain/api/v1/${endpoint}`, {
    headers: {
      'X-API-Key': apiKey,
    },
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

// 使用例
const { contents } = await getContents('your_api_key', 'news');
contents.forEach(content => {
  console.log(content.title);
});

Next.js での使用例 ​

typescript
// app/news/page.tsx
async function getNews() {
  const res = await fetch('https://your-domain/api/v1/news', {
    headers: {
      'X-API-Key': process.env.CMS_API_KEY!,
    },
    next: { revalidate: 60 }, // 60秒キャッシュ
  });

  if (!res.ok) throw new Error('Failed to fetch');
  return res.json();
}

export default async function NewsPage() {
  const { contents } = await getNews();

  return (
    <ul>
      {contents.map((item) => (
        <li key={item.id}>{item.title}</li>
      ))}
    </ul>
  );
}

環境変数の設定 ​

APIキーは環境変数で管理することを推奨します。

bash
# .env.local
CMS_API_KEY=your_api_key_here

セキュリティ注意

APIキーをクライアントサイドのJavaScriptに直接埋め込まないでください。サーバーサイドで使用するか、BFF（Backend for Frontend）経由でアクセスしてください。

関連ページ ​

©2025 Hayato Iwasaki