소스 인벤토리 구조 분석 (iss-bfacccaabbd5)

source-inventory/API_SPEC.md

@@ -0,0 +1,201 @@
+# API Specification
+
+## Base URL
+```
+Development: http://localhost:8080
+Production:  https://api.example.com
+```
+
+---
+
+## Endpoints
+
+### 1. Health Check
+
+**GET** `/health`
+
+**Response (200 OK)**
+```json
+{
+  "status": "UP",
+  "timestamp": "2026-07-10T14:38:23Z"
+}
+```
+
+---
+
+### 2. Get All Users
+
+**GET** `/api/users`
+
+**Response (200 OK)**
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": 1,
+      "username": "user1",
+      "email": "user1@example.com",
+      "createdAt": "2026-07-10T10:00:00Z",
+      "updatedAt": "2026-07-10T10:00:00Z"
+    }
+  ],
+  "message": null
+}
+```
+
+---
+
+### 3. Get User by ID
+
+**GET** `/api/users/{id}`
+
+**Parameters**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | Long | Yes | User ID |
+
+**Response (200 OK)**
+```json
+{
+  "success": true,
+  "data": {
+    "id": 1,
+    "username": "user1",
+    "email": "user1@example.com",
+    "createdAt": "2026-07-10T10:00:00Z",
+    "updatedAt": "2026-07-10T10:00:00Z"
+  },
+  "message": null
+}
+```
+
+**Response (404 Not Found)**
+```json
+{
+  "success": false,
+  "data": null,
+  "message": "User not found with id: 1"
+}
+```
+
+---
+
+### 4. Create User
+
+**POST** `/api/users`
+
+**Request Body**
+```json
+{
+  "username": "newuser",
+  "email": "newuser@example.com"
+}
+```
+
+**Response (201 Created)**
+```json
+{
+  "success": true,
+  "data": {
+    "id": 2,
+    "username": "newuser",
+    "email": "newuser@example.com",
+    "createdAt": "2026-07-10T14:38:23Z",
+    "updatedAt": "2026-07-10T14:38:23Z"
+  },
+  "message": "User created successfully"
+}
+```
+
+**Response (400 Bad Request)**
+```json
+{
+  "success": false,
+  "data": null,
+  "message": "Validation failed: username is required"
+}
+```
+
+---
+
+### 5. Update User
+
+**PUT** `/api/users/{id}`
+
+**Request Body**
+```json
+{
+  "username": "updateduser",
+  "email": "updated@example.com"
+}
+```
+
+**Response (200 OK)**
+```json
+{
+  "success": true,
+  "data": {
+    "id": 1,
+    "username": "updateduser",
+    "email": "updated@example.com",
+    "createdAt": "2026-07-10T10:00:00Z",
+    "updatedAt": "2026-07-10T14:40:00Z"
+  },
+  "message": "User updated successfully"
+}
+```
+
+---
+
+### 6. Delete User
+
+**DELETE** `/api/users/{id}`
+
+**Response (204 No Content)**
+```
+(empty body)
+```
+
+**Response (404 Not Found)**
+```json
+{
+  "success": false,
+  "data": null,
+  "message": "User not found with id: 1"
+}
+```
+
+---
+
+## Common Response Format
+
+All API responses follow this structure:
+
+```json
+{
+  "success": boolean,
+  "data": object | array | null,
+  "message": string | null
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| success | boolean | Operation success status |
+| data | object | Response payload |
+| message | string | Success/error message |
+
+---
+
+## HTTP Status Codes
+
+| Code | Description |
+|------|-------------|
+| 200 | OK - Successful GET, PUT |
+| 201 | Created - Successful POST |
+| 204 | No Content - Successful DELETE |
+| 400 | Bad Request - Validation error |
+| 404 | Not Found - Resource not found |
+| 500 | Internal Server Error - Server error |