1 files changed, 40 insertions, 1 deletions
diff --git a/src/docs/stream.ja.md b/src/docs/stream.ja.md
index 7a2815dba2..1ad36c9020 100644
--- a/src/docs/stream.ja.md
+++ b/src/docs/stream.ja.md
@@ -16,4 +16,43 @@
 
 ## ストリームを経由してAPIリクエストする
 
-ストリームを経由してAPIリクエストすると、HTTPリクエストを発生させずにAPIを利用できます。
+ストリームを経由してAPIリクエストすると、HTTPリクエストを発生させずにAPIを利用できます。そのため、コードを簡潔にできたり、パフォーマンスの向上を見込めるかもしれません。
+
+ストリームを経由してAPIリクエストするには、次のようなメッセージをストリームに送信します:
+```json
+{
+	type: 'api',
+	id: 'xxxxxxxxxxxxxxxx',
+	endpoint: 'notes/create',
+	data: {
+		text: 'yee haw!'
+	}
+}
+```
+
+`id`には、APIのレスポンスを識別するための、APIリクエストごとの一意なIDを設定する必要があります。UUIDや、簡単な乱数のようなもので構いません。
+
+`endpoint`には、あなたがリクエストしたいAPIのエンドポイントを指定します。
+
+`data`には、エンドポイントのパラメータを含めます。
+
+<div class="ui info">
+	<p><i class="fas fa-info-circle"></i> APIのエンドポイントやパラメータについてはAPIリファレンスをご確認ください。</p>
+</div>
+
+### レスポンスの受信
+
+APIへリクエストすると、レスポンスがストリームから次のような形式で流れてきます。
+
+```json
+{
+	type: 'api-res:xxxxxxxxxxxxxxxx',
+	body: {
+		...
+	}
+}
+```
+
+`xxxxxxxxxxxxxxxx`の部分には、リクエストの際に設定された`id`が含まれています。これにより、どのリクエストに対するレスポンスなのか判別することができます。
+
+`body`には、レスポンスが含まれています。