API 入門：ゼロから理解する「プログラム間の対話」

🎯 核心問題

API とは何か？ これは「レストランのメニューはどうデザインすれば、お客様が一目でわかるか？ウェイターはどう注文を取れば、間違えないか？」と尋ねるようなものです。API が解決するのは「プログラム同士がどう対話するか」という問題です。コードを書き始めた最初の日から、あなたは API を使っています。ただ気づいていないだけかもしれません。

0. 初心者によくある3つの困惑

困惑1：API はとても高度なものなのか？

API と聞くと、多くの人は上級エンジニアだけが理解できる概念だと思います。実は、あなたはとっくに API を使っています：

python

len("hello")        # これは Python が提供する API
open("file.txt")    # これも API
requests.get(url)   # これも API

困惑2：Web API と普通の API の違いは？

タイプ	呼び出し対象	通信方式	典型的なシーン
関数 API	ローカルコード	関数呼び出し	`len()`, `open()`
OS API	オペレーティングシステム	システムコール	ファイル読み書き、プロセス作成
Web API	リモートサーバー	HTTP リクエスト	AI モデル呼び出し、天気取得

困惑3：HTTP と SDK のどちらを使うべきか？

python

# HTTP 方式：すべての詳細を自分で処理
import requests
response = requests.post(
    "https://api.deepseek.com/v1/chat/completions",
    headers={"Authorization": "Bearer sk-xxx"},
    json={"model": "deepseek-chat", "messages": [...]}
)
result = response.json()["choices"][0]["message"]["content"]

# SDK 方式：執事が代わりに処理
from openai import OpenAI
client = OpenAI(api_key="sk-xxx")
response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[...]
)
result = response.choices[0].message.content

1. API の本質：プラグとソケット

API（Application Programming Interface、アプリケーションプログラミングインターフェース）は「プログラム間の対話の約束事」です。

1.1 電化製品に例える

概念	電化製品の例え	API 対応
インターフェース	コンセントの形状	関数シグネチャ / URL
入力	電流入力	関数パラメータ / リクエストボディ
出力	電化製品の動作	戻り値 / レスポンスボディ

1.2 3種類の API 形態の比較

TargetLocal code library

CommunicationFunction call

LatencyNanoseconds

Typical scenariosData processing, file operations

Function API example

len("hello")           # returns 5
max([1, 5, 3])         # returns 5
open("file.txt").read() # reads a file

1.3 関数 API と HTTP API の違い

多くの初心者は困惑します：関数 API と HTTP API の違いは何か？ドキュメントを見るときどう区別すればいいのか？

📚 Function API vs HTTP APILocal calls vs network requests: how should you read the docs?

📦Function API

Call styleDirect function call

ParametersArguments inside parentheses

Return valueReturn value directly

Error handlingException or return value

Python example

# Call a built-in function
length = len("hello")      # returns 5

# Call a library function
import math
result = math.sqrt(16)     # returns 4.0

# Call a custom function
def add(a, b):
    return a + b
sum = add(3, 5)            # returns 8

🌐HTTP API

Call styleNetwork request

ParametersURL / body / headers

Return valueJSON/XML response

Error handlingStatus code checks

HTTP request example

POST /v1/chat/completions HTTP/1.1
Host: api.deepseek.com
Authorization: Bearer sk-xxx
Content-Type: application/json

{
  "model": "deepseek-chat",
  "messages": [
    {"role": "user", "content": "Hello"}
  ]
}

Core point:A function API works locally; an HTTP API communicates remotely. Function docs focus on parameters and return values, while HTTP API docs focus on endpoint, authentication, and request/response formats.

1.4 異なるタイプの API ドキュメントの読み方

異なるタイプの API ドキュメントに直面したとき、注目すべきポイントはそれぞれ異なります：

📋 How to Read Different Doc TypesFunction docs, REST API docs, and SDK docs each emphasize different things

Doc typeFunction docs

Best forUsing standard library or third-party functions

Difficulty⭐⭐

🔍 What to focus on

Function signatureParameter typesReturn valueExceptionsExample code

📝Doc example

### json.loads(s, *, cls=None, object_hook=None...)

Parse a JSON string into a Python object.

**Parameters:**
- s (str): JSON string to parse
- cls (JSONDecoder): Custom decoder class
- object_hook (callable): Optional conversion function

**Returns:**
- dict | list: Parsed Python object

**Raises:**
- JSONDecodeError: The string is invalid JSON

**Example:**
>>> import json
>>> json.loads('{"name": "Alice"}')
{'name': 'Alice'}

💡Reading tips

Read the function signature first to see what parameters are needed.
Check parameter types and whether each parameter is required.
Check the return type so later code can handle it correctly.
Notice possible exceptions and prepare error handling.

📊Quick comparison of three doc types

Item

Function docs

REST API docs

SDK docs

Core focus

Parameters, return values

Endpoint, request body

Initialization, method chain

Code example

Function call

HTTP request

Object method

Error handling

Exceptions/return values

Status codes

Exception objects

Read first

Function signature

Base URL + Auth

Quick Start

Reading advice:For function docs, read the signature. For API docs, read the request format. For SDK docs, read examples first. When stuck, look for Quick Start or Getting Started.

2. 1回の完全な API 呼び出し

👇 実際に試してみよう：下のボタンをクリックして、1回の完全な API リクエスト-レスポンスフローを観察してください：

API Request Demo

// Click a command below to simulate API requests

> ▋

💻ClientSends request

Waiting for request...

HTTP Request→

🖥️ServerHandles request

Waiting...

HTTP Response←

📦ResponseReturns result

Waiting for response...

💡 Click a command button to observe a complete API request-response flow.

2.1 API 呼び出しの4段階

段階	何が起きているか	電化製品の例え
リクエスト	クライアントがサーバーにリクエストを送信	スイッチを押す
転送	リクエストがネットワークを通じてサーバーに転送	電流が電線を通る
処理	サーバーがリクエストを処理しデータを返す	電化製品が動作開始
レスポンス	クライアントが返された結果を受信・処理	電球が光る

2.2 レストランの例え

レストランの役割	API 対応	説明
メニュー	API ドキュメント	どんな「料理」が注文できるかを教える
ウェイター	HTTP プロトコル	標準化された「対話方法」
厨房	サーバー	「注文」に従ってリクエストを処理
料理の提供	レスポンス	結果を「お客様」に返す

3. HTTP メソッド：「尋ねている」のか「実行している」のか？

Web API を呼び出すとき、サーバーに何をしたいかを伝える必要があります。これが HTTP メソッドの由来です。

3.1 レストランでの注文で理解する

シーン	実際にどう言うか？	対応する HTTP メソッド
今日のメニューを知りたい	「ウェイター、メニューを見せて」	GET - 純粋に「尋ねる」、データを変更しない
宮保鶏丁を注文したい	「宮保鶏丁をください」	POST - 「実行する」、データを作成
料理を変更したい	「宮保鶏丁を酢豚に変更して」	PUT - データを置換
味を変えたい	「宮保鶏丁のピーナッツ抜きで」	PATCH - 部分修正
不要になった	「やっぱり、あの料理はキャンセルで」	DELETE - データを削除

get

Read

Query data

Idempotent

post

Create

Add data

Not idempotent

put

Full update

Replace resource

Idempotent

patch

Partial update

Modify fields

Not idempotent

delete

Delete

Remove resource

Idempotent

getRead - Query data

Fetch resources from the server without changing data

Restaurant analogy:"Waiter, show me the menu"

GET /api/users           # fetch user list
GET /api/users/123       # fetch one user
GET /api/products?cat=phone  # query phone products

冪等性について

冪等性：複数回実行しても結果は同じか？

冪等な操作（GET/PUT/DELETE）：10 回注文しても 1 回注文しても結果は同じ
非冪等な操作（POST）：10 回注文すると 10 個の注文が作成される可能性がある

解決策：POST 操作は一意の ID で検証し、重複処理を避ける。

3.2 HTTP メソッド早見表

メソッド	用途	冪等性	安全性	典型的なシーン
GET	リソースの取得	あり	あり	リスト検索、詳細表示
POST	リソースの作成	なし	なし	ユーザー追加、注文送信
PUT	全量更新	あり	なし	ユーザープロフィール全体の置換
PATCH	部分更新	なし	なし	ニックネームのみ変更
DELETE	リソースの削除	あり	なし	ユーザー削除、注文キャンセル

4. HTTP ステータスコード：サーバーが何を伝えているのか？

サーバーが応答するとき、まずステータスコードを返し、リクエストが成功したかどうかを伝えます。

4.1 ステータスコードの分類

2xxSuccess

The request was received, understood, and processed successfully

200 OK201 Created204 No Content

3xxRedirect

More action is needed to complete the request

301 Moved Permanently304 Not Modified307 Temporary Redirect

4xxClient error

The request has an error or cannot be completed

400 Bad Request401 Unauthorized403 Forbidden404 Not Found

5xxServer error

The server failed to handle a valid request

500 Internal Error502 Bad Gateway503 Unavailable

💡Memory tip:2️⃣ Success • 3️⃣ Redirect • 4️⃣ Client error • 5️⃣ Server error

4.2 よく使われるステータスコードの詳細

ステータスコード	意味	典型的なシーン	クライアントの処理
200 OK	成功	リクエストが正常に処理された	データを表示
201 Created	作成成功	POST リクエストでリソース作成成功	新リソースに遷移
400 Bad Request	リクエスト形式エラー	パラメータ不足または形式不正	パラメータを確認
401 Unauthorized	未認証	有効な API Key が提供されていない	ユーザーをログインに誘導
403 Forbidden	権限なし	API Key にそのリソースへのアクセス権限がない	権限不足を通知
404 Not Found	存在しない	リクエストしたアドレスやリソースが存在しない	URL を確認
429 Too Many Requests	リクエスト過多	レート制限を超えた	後でリトライ
500 Internal Server Error	サーバーエラー	サーバー側で問題発生	ユーザーに後でリトライするよう通知

👇 実際に試してみよう：下のボタンをクリックして、よく使われるステータスコードの意味を理解しましょう：

HTTP Status Code Demo

// Click a button to inspect status code meanings

> ▋

✅2xx Success

200OKRequest succeeded

201CreatedResource created

204No ContentSucceeded with no response body

⚠️4xx Client errors

400Bad RequestMalformed request

401UnauthorizedNot authenticated

403ForbiddenNo permission

404Not FoundResource missing

422UnprocessableSemantic validation error

429Too ManyToo many requests

🔴5xx Server errors

500Server ErrorInternal server error

502Bad GatewayGateway error

503UnavailableService unavailable

💡 Click a command button to learn common HTTP status codes.

5. HTTP vs SDK：自分で足を運ぶか、執事に任せるか？

5.1 2つの呼び出し方式の比較

	🏃 HTTP API	🤵 SDK
例え	自分で足を運ぶ	執事が代行
長所	✓ すべての言語で使える ✓ リクエストの詳細を完全に制御 ✓ 追加の依存不要	✓ コードが簡潔で読みやすい ✓ 認証を自動処理 ✓ エラーリトライ内蔵
短所	✗ すべての詳細を処理する必要がある ✗ コードが冗長でエラーが発生しやすい	✗ 依存のインストールが必要 ✗ バージョン問題の可能性
コード例	`requests.post(url, json=..., headers={...})`	`client.chat.completions.create(...)`

5.2 どう選ぶか？

シーン	推奨方式	理由
高速開発	SDK	認証、エラー、リトライを自動処理
原理の学習	HTTP	基盤メカニズムを理解
非対応言語	HTTP	どんな言語でも使える
カスタマイズ必要	HTTP	各詳細を柔軟に制御

💡 アドバイス

SDK が使えるなら SDK を使う。面倒なことはライブラリに任せ、時間は自分に残しましょう。

6. API ドキュメントの読み方

API ドキュメントは説明書とメニューを組み合わせたようなものです。最初から最後まで読む必要はなく、「辞書を引く」方法を学べば十分です。

6.1 ドキュメント読解チェックリスト

どんな API ドキュメント（OpenAI や DeepSeek など）を開いても、以下のものだけを探せばよいです：

📖API Document Translator

Base URL

https://api.deepseek.com

Endpoint

POST /v1/chat/completions

Headers

Authorization: Bearer sk-xxx
Content-Type: application/json

Body parameters

modelRequiredModel name

messagesRequiredConversation messages

temperatureOptional0-2, default 1

Translate into code

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxx",
    base_url="https://api.deepseek.com"
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "Hello"}]
)

Core idea:When reading docs, find three things: address (Base URL), authentication (Authorization), and parameters.

項目	説明	例
Base URL	API のルートアドレス	`https://api.deepseek.com`
Authentication	身元をどう証明するか	`Authorization: Bearer sk-xxx`
Endpoints	具体的なインターフェース一覧	`/v1/chat/completions`
Parameters	必須/オプションパラメータ	`model`（必須）、`temperature`（オプション）
Response	返されるデータ構造	`{"choices": [...]}`

6.2 ドキュメントを読む手順

Base URL を見つける - これがすべてのリクエストの接頭辞
認証方式を理解する - API Key は Header か Query か？
必要な Endpoint を見つける - 呼び出す具体的なインターフェース
リクエストパラメータを確認 - どれが必須でどれがオプションか？
返却形式を理解する - データはどう構成されているか？

7. 実践練習：API 呼び出しのシミュレーション

実践なくして理解なし。ここにシミュレーション API があります。パラメータを自由に入力し、アドレスを自由に変更して、何が起きるか見てみましょう。

🧪API PlaygroundTry calls without touching a real server

Endpoint

Method

API Key

Send a request to see the response

Quick tries:

以下のシナリオをトリガーしてみてください：

✅ 成功リクエスト：正しい Endpoint と API Key を入力
❌ 401 エラー：API Key を入力せず、サーバーがどう拒否するかを見る
❌ 404 エラー：存在しないアドレスを入力

8. まとめ

核心ポイント

API は伝言ツール、あなたの言葉を別のコードやリモートサーバーに伝える
あなたはとっくに API を使っている、len() から open() まで、すべて API
Web API は超能力、遠く離れたスーパーコンピュータを呼び出せる
SDK は良い執事、SDK が使えるなら自分で足を運ばない
ドキュメントで探すべき3つ：アドレス、認証、パラメータ

AI プログラミングの時代において、あなたはこれらの核心概念だけを覚えておけば十分です。残りの詳細は、IDE と AI アシスタントが処理してくれます。

用語早見表

用語	正式名称	説明
API	Application Programming Interface	アプリケーションプログラミングインターフェース。ソフトウェア間の相互作用方法を定義
Web API	-	HTTP プロトコルに基づく API、ネットワーク通信に使用
Endpoint	-	エンドポイント、API の具体的なアドレス
HTTP	HyperText Transfer Protocol	Web API が使用する通信プロトコル
GET	-	リソースを取得するメソッド
POST	-	データを送信するメソッド
SDK	Software Development Kit	ソフトウェア開発キット。基盤の API 呼び出しをカプセル化
URL	Uniform Resource Locator	API のネットワークアドレス
JSON	JavaScript Object Notation	よく使われるデータ形式
Authentication	-	身元を検証するプロセス
Status Code	-	HTTP レスポンスのステータスコード
Request	-	リクエスト
Response	-	レスポンス
Header	-	HTTP ヘッダー。メタ情報を含む
Payload	-	リクエストまたはレスポンスの実際のデータ
Rate Limit	-	レート制限
Idempotent	-	冪等。複数回実行しても結果が同じ
REST	Representational State Transfer	API アーキテクチャスタイルの一種
RPC	Remote Procedure Call	リモートプロシージャコール
GraphQL	-	クエリ言語 API の一種
gRPC	-	Google が開発した高性能 RPC フレームワーク

API 入門：ゼロから理解する「プログラム間の対話」 ​

0. 初心者によくある3つの困惑 ​

1. API の本質：プラグとソケット ​

1.1 電化製品に例える ​

1.2 3種類の API 形態の比較 ​

1.3 関数 API と HTTP API の違い ​

1.4 異なるタイプの API ドキュメントの読み方 ​

2. 1回の完全な API 呼び出し ​

2.1 API 呼び出しの4段階 ​

2.2 レストランの例え ​

3. HTTP メソッド：「尋ねている」のか「実行している」のか？ ​

3.1 レストランでの注文で理解する ​

3.2 HTTP メソッド早見表 ​

4. HTTP ステータスコード：サーバーが何を伝えているのか？ ​

4.1 ステータスコードの分類 ​

4.2 よく使われるステータスコードの詳細 ​

5. HTTP vs SDK：自分で足を運ぶか、執事に任せるか？ ​

5.1 2つの呼び出し方式の比較 ​

5.2 どう選ぶか？ ​

6. API ドキュメントの読み方 ​

6.1 ドキュメント読解チェックリスト ​

6.2 ドキュメントを読む手順 ​

7. 実践練習：API 呼び出しのシミュレーション ​

8. まとめ ​

用語早見表 ​

API 入門：ゼロから理解する「プログラム間の対話」

0. 初心者によくある3つの困惑

1. API の本質：プラグとソケット

1.1 電化製品に例える

1.2 3種類の API 形態の比較

1.3 関数 API と HTTP API の違い

1.4 異なるタイプの API ドキュメントの読み方

2. 1回の完全な API 呼び出し

2.1 API 呼び出しの4段階

2.2 レストランの例え

3. HTTP メソッド：「尋ねている」のか「実行している」のか？

3.1 レストランでの注文で理解する

3.2 HTTP メソッド早見表

4. HTTP ステータスコード：サーバーが何を伝えているのか？

4.1 ステータスコードの分類

4.2 よく使われるステータスコードの詳細

5. HTTP vs SDK：自分で足を運ぶか、執事に任せるか？

5.1 2つの呼び出し方式の比較

5.2 どう選ぶか？

6. API ドキュメントの読み方

6.1 ドキュメント読解チェックリスト

6.2 ドキュメントを読む手順

7. 実践練習：API 呼び出しのシミュレーション

8. まとめ

用語早見表