ホーム/ 役に立つAPIドキュメントの書き方：人間とロボットの両方に流暢に話す方法

役に立つAPIドキュメントの書き方：人間とロボットの両方に流暢に話す方法

APIドキュメントは、開発者とユーザーの間の重要な橋です。

川原建

2025年3月6日 • 4 min read

APIドキュメントは、開発者とユーザーの間の重要な橋です。このガイドでは、機械と人間の両方に配慮した、明確かつ親しみやすいドキュメントの作成方法を学びます。効果的なAPIドキュメントは、製品の成功に直結します。

なぜあなたのAPIドキュメントは秘密のラブレターなのか

まずは少しショッキングな事実から始めましょう。ほとんどのAPIドキュメントは人間のためではなく、機械のために書かれています。開発者たちは「技術仕様」を作成しているふりをしますが、実際にはコードスニペットやエンドポイントリストを混乱の黒穴に放り込んでいるだけです。その間に、反対側にいる可哀そうな人間—それがジュニア開発者であれ、睡眠不足のCTOであれ—は、画面を見つめながら「これ、いったい何をするの？」と呟いています。

ここでの認知的なひねりはこうです：素晴らしいAPIドキュメントはロボットだけのものではありません。それは冷たい論理的な機械と、混沌とした感情的な人間との間の橋です。バイナリを話すゲストと、コーヒーを飲みながら締切について愚痴る別のゲストの間の通訳のようなものです。このバランスを取ることができれば、あなたのAPIは使う喜びに満ちたものになります。失敗すれば、サポートチケットの山に埋もれることになります。

ロボットと人間が大好きになるドキュメントの書き方ガイド

ステップ1：エンドポイントを5歳児に説明するかのように設計する

機械は構造を気にしますが、人間は明快さを求めます。エンドポイントの名前を付けるときは、あまり技術的でない親戚でも理解できるようにしましょう。

✅ 良い例：
GET /users/{id}/orders → 「特定のユーザーのすべての注文を取得します。」

❌ 悪い例：
GET /u/123/ords → 「??? これはユーザーに関するもの？それともユニコーン？」

プロのヒント: EchoAPIを使ってリアルタイムでエンドポイントをモックおよびテストできます。視覚的なエディターを使うことで、あなたのURLが人間と機械にどう見えるかを確認できます。

ステップ2：人間に優しい説明を書く

あなたのドキュメントは博士号論文ではありません。平易な英語を使い、各パラメータの*「なぜ？」*を答えましょう。

例:

## `GET /products`
- **何をするか**: 利用可能な製品のリストを表示します。  
- **なぜ重要か**: これを使用してアプリのショッピングカタログを埋めることができます。  
- **パラメータ**:  
  - `category`（オプション）: カテゴリでフィルタリング。例: `"electronics"`。  
  - `limit`（デフォルト: 10）: 返す結果の数。最大100。

ステップ3：人を泣かせないコード例を追加する

人間はコピー＆ペーストで学びます。サポートする主要な言語ごとに動作するコードを提供しましょう。

JavaScriptの例:

// EchoAPIのSDKを使って製品を取得  
const response = await EchoAPI.get('/products', {  
  params: { category: 'electronics', limit: 20 }  
});  
console.log(response.data);

Pythonの例:

# Pythonで製品を取得  
import requests  
response = requests.get(  
  'https://api.yourservice.com/products',  
  params={'category': 'electronics', 'limit': 20}  
)  
print(response.json())

なぜこれが機能するのか: 開発者はこのコードを利用して適宜調整し、すぐに結果を見ることができます。

ステップ4：エラーをセラピストのようにドキュメントする—明確で親切で役立つ

一般的な「404 Not Found」は、「あなたが間違っています！」と叫ぶようなものです。代わりに:

✅ 良いエラー:

{  
  "error": {  
    "code": 404,  
    "message": "ユーザーが見つかりません。IDが正しいか、ユーザーが存在するか確認してください。",  
    "fix": "まずGET /usersでユーザーを検索してみてください。"  
  }  
}