api-reference-guide

API リファレンスガイドの作成

開発者が喜んで使う、包括的な API ドキュメントの作成に精通しています。

基本原則

• 開発者を第一に考えるアプローチ：API を導入する人の視点で書きます
• 簡潔さより明瞭さを重視：十分な詳細を提供します
• 一貫性：パターンを統一します
• 網羅性：すべてのエンドポイント、パラメーター、応答、エッジケースを網羅します
• テスト可能性：実行可能なサンプルを含めます

リファレンスの構成

1. 概要 — API の目的、ベース URL、バージョニング戦略
2. 認証 — メソッド、トークン、ヘッダー、サンプル
3. エンドポイント — リソースごとにグループ化
4. エラー処理 — 標準的なエラーコードと応答
5. リクエスト頻度の制限 — 制限、ヘッダー
6. SDK とライブラリ — 利用可能なクライアントライブラリ
7. 変更履歴 — バージョン履歴

認証ドキュメント

# API Key Authentication
curl -X GET "https://api.example.com/v1/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

// JavaScript SDK Example
const client = new APIClient({
  apiKey: 'your-api-key',
  baseURL: 'https://api.example.com/v1'
});

エンドポイントドキュメントの形式

GET /users/{id}

ID で特定のユーザーを取得します。

パラメーター：

パラメーター	型	場所	必須	説明
id	string	path	はい	ユーザーの一意の ID
include	string	query	いいえ	カンマ区切りの関連リソース

リクエスト例：

curl -X GET "https://api.example.com/v1/users/12345?include=profile,settings" \
  -H "Authorization: Bearer YOUR_API_KEY"

応答（200 OK）：

{
  "id": "12345",
  "email": "[email protected]",
  "created_at": "2023-01-15T10:30:00Z",
  "profile": {
    "first_name": "John",
    "last_name": "Doe"
  }
}

POST /users

新しいユーザーアカウントを作成します。

リクエスト本文：

{
  "email": "string (обязательный)",
  "password": "string (обязательный, минимум 8 символов)",
  "profile": {
    "first_name": "string (опциональный)",
    "last_name": "string (опциональный)"
  }
}

応答（201 Created）：

{
  "id": "12346",
  "email": "[email protected]",
  "created_at": "2024-01-15T14:30:00Z"
}

エラードキュメント

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "email",
        "message": "Email address is required"
      }
    ],
    "request_id": "req_1234567890"
  }
}

HTTP ステータスコード：

コード	ステータス	説明
200	OK	リクエスト成功
201	Created	リソースを作成しました
400	Bad Request	検証エラー
401	Unauthorized	無効またはトークンがありません
403	Forbidden	権限が不足しています
404	Not Found	リソースが見つかりません
429	Too Many Requests	リクエスト制限を超過しました
500	Internal Server Error	サーバーエラー

言語別のサンプル

Python

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.example.com/v1/users/12345',
    headers=headers
)
print(response.json())

Node.js

const fetch = require('node-fetch');

const response = await fetch('https://api.example.com/v1/users/12345', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
const data = await response.json();
console.log(data);

Go

req, _ := http.NewRequest("GET", "https://api.example.com/v1/users/12345", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

データ型とスキーマ

User:
  type: object
  properties:
    id:
      type: string
      description: Unique user identifier
      example: "usr_1234567890"
    email:
      type: string
      format: email
      description: User's email address
    created_at:
      type: string
      format: date-time
      description: ISO 8601 timestamp
    status:
      type: string
      enum: [active, inactive, suspended]
      description: Current account status

高度な機能

フィルタリング

GET /users?filter[status]=active&filter[role]=admin

ページネーション

GET /users?page=2&limit=20

Response headers:
X-Total-Count: 150
X-Page: 2
X-Per-Page: 20
Link: <https://api.example.com/v1/users?page=3>; rel="next"

ソート

GET /users?sort=-created_at,email

マイナス記号は降順でのソートを示します。

フィールドの選択

GET /users?fields=id,email,created_at

冪等性

curl -X POST "https://api.example.com/v1/payments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{"amount": 1000}'

レート制限ヘッダー

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

ベストプラクティス

1. 一貫した命名（snake_case または camelCase）を使用します
2. 現実的なデータのサンプルを含めます
3. 成功時とエラー時の両方の応答例を示します
4. オプションおよび必須のパラメーターをドキュメント化します
5. リクエスト頻度の制限に関する情報を含めます
6. OpenAPI/Swagger 仕様を使用します
7. 非推奨の通知を追加します
8. 公開前にすべてのコードサンプルをテストします