포인트 기반 커피 주문 결제 시스템 (API 명세서 개선)

2026.03.30 - [트러블슈팅] - 기능 중심 API 설계의 한계와 도메인 중심으로의 개선 과정

기능 중심 API 설계의 한계와 도메인 중심으로의 개선 과정

 

🗂️ API 명세서

기능 분류	기능명	API Path	Method	설명
user	사용자 목록 조회	/api/users	GET	전체 사용자 목록 조회
	사용자 단건 조회	/api/users/{userId}	GET	사용자 정보 조회
	사용자 포인트 조회	/api/users/{userId}/points	GET	사용자의 현재 포인트 조회
	포인트 충전	/api/users/{userId}/points/charge	POST	포인트 충전 및 잔액 증가
menu	메뉴 목록 조회	/api/menus	GET	전체 메뉴 목록 조회
	메뉴 단건 조회	/api/menus/{menuId}	GET	메뉴 상세 조회
	인기 메뉴 조회	/api/menus/popular	GET	최근 7일 기준 인기 메뉴 3개 조회
order	주문 생성 + 결제	/api/orders	POST	주문 생성 및 포인트 결제 처리
	주문 단건 조회	/api/orders/{orderId}	GET	주문 상세 조회
order_item	주문 상품 조회	/api/orders/{orderId}/items	GET	주문에 포함된 메뉴 정보 조회
payment	결제 조회	/api/payments/{orderId}	GET	주문에 대한 결제 정보 조회
pointhistory	포인트 이력 조회	/api/points/history/{userId}	GET	포인트 충전/사용 이력 조회

---

1. User

사용자 목록 조회

GET /api/users

 

Response

{
    "code": 200,
    "data": [
        {
            "id": 1,
            "point": 0.00
        },
        {
            "id": 2,
            "point": 1000.00
        },
        {
            "id": 3,
            "point": 2500.00
        },
        {
            "id": 4,
            "point": 5000.00
        },
        {
            "id": 5,
            "point": 8000.00
        },
        {
            "id": 6,
            "point": 12000.00
        },
        {
            "id": 7,
            "point": 20000.00
        },
        {
            "id": 8,
            "point": 30000.00
        },
        {
            "id": 9,
            "point": 50000.00
        },
        {
            "id": 10,
            "point": 100000.00
        }
    ],
    "success": true
}

---

사용자 단건 조회

GET /api/users/{userId}

 

Response

{
    "code": 200,
    "data": {
        "id": 1,
        "point": 0.00
    },
    "success": true
}

---

사용자 포인트 조회

GET /api/users/{userId}/points

 

Response

{
    "code": 200,
    "data": {
        "point": 0.00,
        "userId": 1
    },
    "success": true
}

---

포인트 충전

POST /api/users/{userId}/points/charge

 

Request

{
  "amount": 50000
}

 

Response

{
    "code": 200,
    "data": {
        "point": 50000.00,
        "userId": 1
    },
    "success": true
}

---

2. Menu

메뉴 목록 조회

GET /api/menus

 

Response

{
    "code": 200,
    "data": [
        {
            "menuId": 1,
            "name": "아메리카노",
            "price": 4500.00
        },
        {
            "menuId": 2,
            "name": "카페라떼",
            "price": 5000.00
        },
        {
            "menuId": 3,
            "name": "바닐라라떼",
            "price": 5500.00
        },
        {
            "menuId": 4,
            "name": "카푸치노",
            "price": 5000.00
        },
        {
            "menuId": 5,
            "name": "콜드브루",
            "price": 4800.00
        },
        {
            "menuId": 6,
            "name": "카라멜마끼아또",
            "price": 5700.00
        },
        {
            "menuId": 7,
            "name": "헤이즐넛라떼",
            "price": 5500.00
        },
        {
            "menuId": 8,
            "name": "아인슈페너",
            "price": 6000.00
        },
        {
            "menuId": 9,
            "name": "초코라떼",
            "price": 5300.00
        },
        {
            "menuId": 10,
            "name": "녹차라떼",
            "price": 5200.00
        }
    ],
    "success": true
}

---

메뉴 단건 조회

GET /api/menus/{menuId}

 

Response

{
    "code": 200,
    "data": {
        "menuId": 1,
        "name": "아메리카노",
        "price": 4500.00
    },
    "success": true
}

---

인기 메뉴 조회

GET /api/menus/popular

 

Response

{
    "code": 200,
    "data": [
        {
            "menuId": 1,
            "name": "아메리카노",
            "orderCount": 3
        },
        {
            "menuId": 4,
            "name": "카푸치노",
            "orderCount": 1
        },
        {
            "menuId": 7,
            "name": "헤이즐넛라떼",
            "orderCount": 1
        }
    ],
    "success": true
}

---

3. Order

주문 생성 + 결제

POST /api/orders

 

Request

{
  "userId": 1,
  "menuId": 1
}

 

Response

{
    "code": 201,
    "data": {
        "orderId": 1,
        "orderedAt": "2026-03-30T17:43:25.5616942",
        "status": "COMPLETED",
        "totalPrice": 4500.00,
        "userId": 1
    },
    "success": true
}

---

주문 단건 조회

GET /api/orders/{orderId}

 

Response

{
    "code": 200,
    "data": {
        "orderId": 1,
        "orderedAt": "2026-03-30T17:43:25.561694",
        "status": "COMPLETED",
        "totalPrice": 4500.00,
        "userId": 1
    },
    "success": true
}

---

주문 상품 조회

GET /api/orders/{orderId}/items

 

Response

{
    "code": 200,
    "data": [
        {
            "menuId": 1,
            "name": "아메리카노",
            "orderItemId": 1,
            "price": 4500.00
        }
    ],
    "success": true
}

---

4. Payment

결제 조회

GET /api/payments/{orderId}

 

 

Response

{
    "code": 200,
    "data": {
        "amount": 4500.00,
        "orderId": 1,
        "paidAt": "2026-03-30T17:43:25.569694",
        "paymentId": 1,
        "status": "SUCCESS",
        "userId": 1
    },
    "success": true
}

---

5. PointHistory

포인트 이력 조회

GET /api/points/history/{userId}

 

Response

{
    "code": 200,
    "data": [
        {
            "amount": -4500.00,
            "createdAt": "2026-03-30T17:43:25.568693",
            "historyId": 2,
            "status": "USE"
        },
        {
            "amount": 50000.00,
            "createdAt": "2026-03-30T17:43:15.740768",
            "historyId": 1,
            "status": "CHARGE"
        }
    ],
    "success": true
}

---

⭐ 핵심 변화 포인트

• point 도메인을 user 하위로 이동하여 책임 명확화
• 주문 + 결제 + 포인트 차감 흐름을 order 중심으로 통합
• order_item을 독립 기능이 아닌 order의 하위 리소스로 재정의
• 기능 기준 API → 도메인 책임 기준 API로 구조 개선