RESTful API リファレンス

BluePeriodが提供するRESTful APIの概要と利用方法について説明します。エンドポイントの詳細な仕様は Scalar UI で確認してください。

1. 概要

BluePeriod RESTful API（/v1/）は、公開された作品の閲覧・検索・管理を行うための外部公開APIです。API Key認証が必須であり、レートリミットが適用されます。

1.1. ベースURL

https://blueperiod.blue/api/v1

1.2. 認証方式

API Key認証: Authorization: Bearer <key> ヘッダーによる認証

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://blueperiod.blue/api/v1/projects

1.3. API Keyの発行

Settings画面の「Developer API Keys」セクションから発行可能です。

権限スコープ: ["read"]（読み取り専用）、["read", "write"]（読み書き）
プレフィックス: 発行時に表示されるプレフィックス（例: bp_abc123...）で管理画面で識別可能

1.4. レートリミット

API Key単位のリクエスト制限が適用されます。

スコープ	制限
read	300 req/hour
write	60 req/hour

レスポンスヘッダーで確認可能：

X-RateLimit-Limit: 制限値
X-RateLimit-Remaining: 残りリクエスト数
X-RateLimit-Reset: リセット時刻（Unix timestamp）

2. Scalar UI — インタラクティブなAPIドキュメント

エンドポイントの詳細な仕様、リクエスト/レスポンス例、認証テストは Scalar UI で確認してください。

2.1. APIドキュメントへのアクセス

https://blueperiod.blue/api/v1/docs

Scalar UI では以下が可能です：

エンドポイント一覧: Public API / Developer API の全エンドメントを確認
インタラクティブなテスト: API Keyを設定して実際にリクエストを送信可能
リクエスト/レスポンス例: 各エンドポイントの使用例を確認
スキーマ定義: 型定義やバリデーションルールを確認

2.2. 主なエンドポイントカテゴリ

カテゴリ	説明
Public API	公開作品の閲覧・検索（認証必須）
Developer API	自分のリソース管理（認証必須）

3. OpenAPI仕様書 — 機械可読な仕様書

OpenAPI 3.0仕様書をJSON形式で取得可能です。Swagger/OpenAPI対応ツールでの自動生成等に使用できます。

3.1. 仕様書の取得

GET /v1/openapi.json

3.2. 自動生成

仕様書は @hono/zod-openapi でコードから自動生成されており、常に最新の実装と同期されています。

4. エラーレスポンス

4.1. 認証エラー（401）

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

4.2. レートリミット超過（429）

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded",
  "retry-after": 3600
}

4.3. リソース不在（404）

{
  "error": "Not Found",
  "message": "Resource not found"
}

5. クイックスタート

5.1. 最初のリクエスト

Settings画面でAPI Keyを発行
Scalar UI（/v1/docs）にアクセス
右上の「Authorize」ボタンでAPI Keyを設定
任意のエンドポイントで「Try it」を実行

5.2. curlからのリクエスト

# 公開プロジェクト一覧
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://blueperiod.blue/api/v1/projects

# プロジェクト詳細
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://blueperiod.blue/api/v1/projects/{id}

# 目次
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://blueperiod.blue/api/v1/projects/{id}/toc

6. 関連ドキュメント

05_api_specification — 内部API（/api/*）の仕様
04_database_schema_supabase — データベーススキーマ
16_backend_architecture — バックエンドアーキテクチャ

RESTful API リファレンス

On this page