From 2830148f1c15d07257c61a723d3fa02687243d7a Mon Sep 17 00:00:00 2001
From: aoi-dev-0411 <aoikabu12@gmail.com>
Date: Sat, 11 Apr 2026 11:54:29 +0900
Subject: [PATCH] docs: add API example requests and responses to README #30

---
 README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/README.md b/README.md
index cf3422c..44f4662 100644
--- a/README.md
+++ b/README.md
@@ -171,6 +171,59 @@ pnpm run dev
 
 ---
 
+## 📡 API Examples
+
+### Compare two developers
+
+**Request:**
+```bash
+GET /api/compare?username=torvalds&username=gvanrossum
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "users": [
+    {
+      "username": "torvalds",
+      "repoScore": 9850,
+      "prScore": 120,
+      "contributionScore": 45,
+      "finalScore": 4552,
+      "topRepos": [
+        { "name": "linux", "stars": 180000, "forks": 52000 }
+      ],
+      "topPullRequests": []
+    },
+    {
+      "username": "gvanrossum",
+      "repoScore": 4200,
+      "prScore": 980,
+      "contributionScore": 310,
+      "finalScore": 2370,
+      "topRepos": [
+        { "name": "cpython", "stars": 61000, "forks": 29000 }
+      ],
+      "topPullRequests": [
+        { "title": "bpo-12345: fix typing module", "repo": "python/cpython" }
+      ]
+    }
+  ]
+}
+```
+
+### Error response (user not found)
+
+```json
+{
+  "success": false,
+  "error": "GitHub user not found"
+}
+```
+
+---
+
 ## 🌍 Localization
 
 * Supported languages: English 🇺🇸, Arabic 🇸🇦