API仕様書の作成
この講座はコースの最初のステップです。成果物作成の第一歩として、これから構築するAPIの仕様書を作成します。ポートフォリオとして提出できる品質を目指し、「このドキュメントだけでフロントエンド開発者が実装できるか？」を基準に仕上げましょう。
- 期待するAPIのレベルを理解する
- API仕様書に含めるべき項目を整理する
- 自分のテーマに沿ったAPI仕様書を作成する
1. 期待するAPIのレベル
本コースはインフラの構築・自動化が主体です。APIの複雑さよりも、インフラ上で正しく動作するアプリケーションを完成させることを重視してください。
1.1 最低限のレベル
1つのリソース（例：タスク、ユーザなど）に対して、以下の5つのエンドポイントを持つREST APIを設計できればOKです。
| 操作 | メソッド | エンドポイント例 | 説明 |
|---|---|---|---|
| index | GET | /api/v1/tasks | 一覧取得 |
| show | GET | /api/v1/tasks/{id} | 詳細取得 |
| create | POST | /api/v1/tasks | 新規作成 |
| update | PUT | /api/v1/tasks/{id} | 更新 |
| delete | DELETE | /api/v1/tasks/{id} | 削除 |
1.2 余裕がある場合
以下のような応用に挑戦しても構いません。
- ログイン・認証機能の追加
- 複数のリソースを扱う設計（例：ユーザとタスクのリレーション）
1.3 画面（フロントエンド）について
画面の作成は任意です。シンプルなAPIだけで問題ありません。ただし、画面を作りたい方はフロントエンドも含めて取り組んでいただいて構いません。
2. 必須要件
以下の項目をすべて含むAPI仕様書を作成してください。形式はマークダウン、Googleスプレッドシート、Excelなど自由です。
2.1 API全体に関する項目
- APIの概要 … どんな機能を持つAPIか、対象となるリソースは何かを記載する
- 共通仕様 … ベースURL、日時フォーマット、ページネーションの仕様などを記載する
- 認証方式 … APIの認証方法（APIキー、Bearer Token など）を記載する
- ステータスコード一覧 … API全体で使用するHTTPステータスコードとその意味を一覧にまとめる
- エンドポイント一覧 … 全APIのメソッド・パス・概要を一覧表にまとめる
2.2 各APIの詳細仕様（すべてのエンドポイントについて記載）
- リクエストパラメータ … パラメータ名・型・必須/任意・説明を表形式で記載する
- リクエストボディのJSON例 … 実際のリクエスト例をJSONで記載する
- レスポンス … フィールド名・型・説明を表形式で記載する
- レスポンスのJSON例 … 実際のレスポンス例をJSONで記載する
- エラーレスポンス … 想定されるエラーのステータスコードとエラー内容を記載する
3. 提出物
- API仕様書のファイル（形式自由）
4. サンプル
以下はユーザ管理APIを例にしたサンプルです。参考にしてください。
# ユーザ管理API仕様書
## APIの概要
ユーザ情報を管理するREST APIです。ユーザの登録・取得・更新・削除（CRUD）機能を提供します。
## 共通仕様
- ベースURL: https://api.example.com/api/v1
- 日時フォーマット: ISO 8601（例: 2026-04-03T12:00:00Z）
- ページネーション: クエリパラメータ page（デフォルト: 1）、per_page（デフォルト: 20、最大: 100）
## 認証方式
すべてのAPIリクエストにBearerトークンが必要です。
Authorization: Bearer <access_token>
## ステータスコード一覧
| ステータスコード | 意味 |
|-----------------|------|
| 200 | リクエスト成功 |
| 201 | リソース作成成功 |
| 400 | バリデーションエラー |
| 401 | 認証エラー |
| 404 | リソースが見つからない |
| 409 | リソースの競合（重複など） |
| 500 | サーバ内部エラー |
## エンドポイント一覧
| No. | API ID | API名 | メソッド | エンドポイント |
|-----|--------|--------|----------|----------------|
| 1 | API-001 | ユーザ登録 | POST | /api/v1/users |
| 2 | API-002 | ユーザ一覧取得 | GET | /api/v1/users |
| 3 | API-003 | ユーザ詳細取得 | GET | /api/v1/users/{userId} |
| 4 | API-004 | ユーザ更新 | PUT | /api/v1/users/{userId} |
| 5 | API-005 | ユーザ削除 | DELETE | /api/v1/users/{userId} |
## API詳細
### API-001 ユーザ登録
リクエストパラメータ:
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| name | string | ○ | ユーザ名（最大50文字） |
| email | string | ○ | メールアドレス（一意制約あり） |
| password | string | ○ | パスワード（8文字以上、英数記号） |
リクエストボディのJSON例:
{
"name": "山田太郎",
"email": "yamada@example.com",
"password": "P@ssw0rd123"
}
レスポンス（201 Created）:
| フィールド名 | 型 | 説明 |
|-------------|------|------|
| id | integer | ユーザID |
| name | string | ユーザ名 |
| email | string | メールアドレス |
| createdAt | string | 作成日時（ISO 8601） |
レスポンスのJSON例:
{
"id": 1,
"name": "山田太郎",
"email": "yamada@example.com",
"createdAt": "2026-04-03T12:00:00Z"
}
エラーレスポンス:
| ステータスコード | エラー内容 |
|-----------------|-----------|
| 400 | バリデーションエラー（必須項目の不足、形式不正など） |
| 409 | メールアドレスの重複 |
| 500 | サーバ内部エラー |
5. 作成のヒント
- まずはエンドポイント一覧を洗い出し、全体像を整理してから詳細に進むとスムーズです
- パスパラメータ（{userId}）とクエリパラメータ（?page=1）の違いを意識しましょう
6. 参考講座
- Python基本文法
- Python制御構文
- Pythonデータ構造
- Python関数とクラス
- Pythonライブラリ
- Python応用構文
- データベースとは
- SQL基本文法
- Webアプリケーションの基本
- FastAPI入門
- SQLModel入門
- PythonでREST APIを作ろう
7. 目安期間
1週間
8. （任意）フロントエンドについて
本コースではフロントエンド（画面）の作成は必須ではありません。シンプルなAPIだけで全ステップを進めることができます。
ただし、「画面も作ってみたい」という方は、フロントエンドにも挑戦していただいて構いません。画面を作成する場合は、このステップで以下の設計資料も合わせて作成してみましょう。
8.1 画面レイアウト
各画面にどのような要素（入力欄、ボタン、一覧表示など）を配置するかを、ワイヤーフレームとして作成します。draw.io、Figma、手書きスキャンなど、ツールは自由です。
8.2 画面遷移図
画面同士のつながり（どのボタンを押すとどの画面に遷移するか）がわかる資料を作成します。ユーザの操作フローを可視化することで、実装時に迷わず進められます。
| 💡 ポイント |
|---|
| フロントエンド開発（HTML/CSS/JavaScript、React、Next.jsなど）はDevOps Campの講座には含まれていないため、独学で進めていただく形になります。わからないことがあれば相談いただくことは可能ですが、講座のようなステップバイステップの教材は用意されていない点をご了承ください。 |
9. アプリ開発をスキップしたい場合
本コースはインフラ構築・自動化が主体のため、「APIの設計や開発よりもインフラに集中したい」という方は、アプリ開発（このステップとステップ3：API構築）をスキップすることができます。
その場合は、こちらで用意しているサンプルアプリケーションを使用して、次のAWS構成図の作成から取り組んでください。
9.1 サンプルAPI（必須）
以下のリポジトリにサンプルのREST APIを用意しています。このAPIをそのままステップ4以降のインフラ構築で使用できます。
9.2 サンプルフロントエンド（任意）
フロントエンド（画面）も合わせて使いたい場合は、以下のリポジトリも利用できます。フロントエンドの利用は任意ですので、APIのみで進めても問題ありません。
9.3 利用にあたって
それぞれのリポジトリのREADME.mdに、アプリケーションの概要や起動手順などが記載されています。API仕様についてはAPIリポジトリのREADME.mdに記載があります。
まずはREADME.mdの内容を一通り読み、アプリケーションの全体像を把握した上で、次のAWS構成図の作成に取り組んでください。
なお、README.mdの記載は実業務を意識して、あえて簡潔な記載にとどめています。実務でも、すべてが丁寧にドキュメント化されているとは限りません。わからない点や不明な点があれば、遠慮なくご相談ください。それも含めて学びの一環です。