# API設計書

## 概要

本ドキュメントは、Oh My Zsh プロジェクトにおける外部API連携の設計を記載しています。

Oh My Zsh は Zsh シェルの設定管理フレームワークであり、**自身でAPIエンドポイントを公開するWebアプリケーションではありません**。ただし、プロジェクトの自動化スクリプト（依存関係更新ツール）が外部APIをクライアントとして利用しています。

本設計書では、プロジェクト内で利用されている外部API連携について記載します。

## 外部API連携一覧

| カテゴリ | API | 利用箇所 | 説明 |
| --- | --- | --- | --- |
| GitHub API | REST API v3 | `.github/workflows/dependencies/updater.py` | 依存関係の更新チェック |

## GitHub API連携

### 利用目的

Oh My Zsh プロジェクトでは、プラグインやテーマの依存関係を自動的に更新するために GitHub API を利用しています。この機能は GitHub Actions ワークフローで実行されます。

### 認証方式

```
Authorization: Bearer {GH_TOKEN}
Accept: application/vnd.github+json
```

環境変数 `GH_TOKEN` から GitHub Personal Access Token または GitHub App Token を取得して認証を行います。

### 利用エンドポイント

#### 1. タグ一覧取得

新しいタグ（バージョン）が存在するかを確認するために使用します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET https://api.github.com/repos/{owner}/{repo}/git/refs/tags` |
| 認証 | 必要（レート制限回避のため） |
| 利用ファイル | `.github/workflows/dependencies/updater.py` |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| owner | string | ○ | リポジトリオーナー名 |
| repo | string | ○ | リポジトリ名 |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
[
  {
    "ref": "refs/tags/v1.0.0",
    "node_id": "...",
    "url": "https://api.github.com/repos/{owner}/{repo}/git/refs/tags/v1.0.0",
    "object": {
      "sha": "abc123...",
      "type": "commit",
      "url": "..."
    }
  }
]
```

**利用方法**

```python
url = f"https://api.github.com/repos/{repo}/git/refs/tags"
response = requests.get(url, headers=HEADERS)
```

#### 2. コミット比較

現在のバージョンと最新バージョンの差分を確認するために使用します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| エンドポイント | `GET https://api.github.com/repos/{owner}/{repo}/compare/{base}...{head}` |
| 認証 | 必要（レート制限回避のため） |
| 利用ファイル | `.github/workflows/dependencies/updater.py` |

**パスパラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| owner | string | ○ | リポジトリオーナー名 |
| repo | string | ○ | リポジトリ名 |
| base | string | ○ | 比較元のコミットSHA |
| head | string | ○ | 比較先のブランチ名 |

**レスポンス（成功時）**

ステータスコード: `200 OK`

```json
{
  "status": "ahead",
  "permalink_url": "https://github.com/{owner}/{repo}/compare/...",
  "commits": [
    {
      "sha": "def456...",
      "html_url": "https://github.com/{owner}/{repo}/commit/def456..."
    }
  ]
}
```

**利用方法**

```python
url = f"https://api.github.com/repos/{repo}/compare/{version}...{branch}"
response = requests.get(url, headers=HEADERS)
```

### エラーハンドリング

| ステータスコード | 説明 | 対応 |
| --- | --- | --- |
| 200 | 成功 | レスポンスを解析して処理を続行 |
| 401 | 認証エラー | GH_TOKEN の設定を確認 |
| 403 | レート制限またはアクセス拒否 | 認証トークンを使用、または待機 |
| 404 | リポジトリまたはリファレンスが存在しない | 依存関係設定を確認 |

```python
if response.status_code == 200:
    data = response.json()
    # 処理を続行
else:
    raise Exception(
        f"GitHub API request failed with status code {response.status_code}: {response.json()}"
    )
```

## GitHub CLI 連携

依存関係更新ツールは、GitHub CLI (`gh`) を使用して Issue と Pull Request を作成します。

### Issue 作成

```bash
gh issue create -t "{title}" -b "{body}"
```

### Pull Request 作成

```bash
gh pr list --state open --head {branch} --json title
gh pr create -B {default_branch} -H {branch} -t "{title}" -b "{body}"
```

## 備考

- このプロジェクトは Web API サーバーではないため、独自のAPIエンドポイントは公開していません
- 上記の GitHub API 連携は、CI/CD パイプライン（GitHub Actions）内でのみ実行されます
- 依存関係更新ツールのソースコード: `.github/workflows/dependencies/updater.py`
- プロキシ設定ツール（`plugins/shell-proxy/`）は外部APIを呼び出すクライアントではなく、ローカル環境変数を設定するユーティリティです
