API 概要

KUKAN は用途に応じて 4 種類の API を提供します。

API	パス	用途
REST API (v1)	/api/v1/*	KUKAN ネイティブの API。推奨
CKAN 互換 API	/api/3/action/*	CKAN 既存ツールとの互換性
MCP サーバー	/api/mcp	AI エージェント連携（Model Context Protocol）
OData フィード	/odata/v1/resources/*	BI ツールが表として開く（読み取り専用）

ベース URL

https://your-kukan-site

レスポンス形式

REST API は標準的な JSON を返します。エラーは RFC 7807 Problem Details 形式です。

{
  "type": "about:blank",
  "title": "NOT_FOUND",
  "status": 404,
  "detail": "Package not found: my-dataset"
}

CKAN 互換 API は CKAN の慣習に従い以下の形式を返します。

{
  "help": "https://your-kukan-site/api/3/action/...",
  "success": true,
  "result": { ... }
}

ページネーション

一覧エンドポイントは offset / limit クエリパラメータでページネーションを指定します。

GET /api/v1/packages?offset=0&limit=20

レスポンスは以下の形式です。

{
  "items": [...],
  "total": 123,
  "offset": 0,
  "limit": 20
}

レート制限

一般の API に回数の制限はありませんが、認証エンドポイント（/api/auth/*）と AI メタデータ提案には上限があります（超過時は 429）。表のクエリと OData は、呼び出し元ごとに同時に実行できる数に上限があります（超過時は 429 と Retry-After）。AWS のサイトでは、WAF が IP アドレスごとのリクエスト数で止める設定になっていることもあります。大量のリクエストを送る場合は運用側にご相談ください。