🚩[3단계-1] 내 프로젝트 맞춰 만들어보는 API 스펙

📈  [3단계-1] 내 프로젝트 맞춰 만들어보는 API 스펙

---

🚩 왜 API 스펙을 먼저 작성할까?

---

1. 📚 프론트엔드와 협업을 위한 '계약서'

• 백엔드가 API를 어떻게 만들건지 먼저 정리해두는 거야.
• 프론트는 이 스펙을 보고:
  • 어떤 URL로
  • 어떤 요청 데이터를 보내야 하고
  • 어떤 응답 데이터를 받을지
• 미리 알 수 있어.

👉 즉, API 스펙 = 프론트랑 백엔드 사이 약속!

---

2. ⚡ 프론트엔드 개발이 '동시에' 가능

• 프론트 개발자는 백엔드 완성 기다리지 않고
  mock 데이터(가짜 데이터)로 프론트 개발을 시작할 수 있어.
• 백엔드 개발자는 이 스펙 기준으로 API를 만들면 되고.

👉 서로 독립적으로 개발, 프로젝트 전체 속도 엄청 빨라짐!

---

3. 🚀 초기 기획 오해 방지

• 만들다가 "어? 이거 API에 없는데?"
• "이거 데이터 빠졌는데?" 이런거 나오면 프로젝트 터짐.

미리:

• 어떤 기능
• 어떤 데이터 구조
• 어떤 요청/응답 방식
• 어떤 HTTP 메서드 (GET, POST, PATCH...)

이걸 다 정리해놓으면,
👉 처음부터 프론트, 백엔드, 기획팀이 같은 그림을 그리고 시작할 수 있어.

---

📚 요약

왜 해야 하나?이유

✅ 프론트-백 협업 기준서	API 요청/응답 형식 미리 정의
✅ 개발 동시 진행 가능	프론트는 스펙 보고 mock 개발, 백은 실제 API 개발
✅ 기획, 설계 오해 방지	개발 중 큰 수정/충돌 방지

 

---

💡 정리 한줄

👉 API 스펙은 프론트와 백엔드가 같은 언어로 말하게 해주는 '계약서'다.

---

그래서 지금 작성한 이 API 스펙을 프론트팀에 공유하면

🔥 "우리 이 스펙 기준으로 개발할게요!"

하고 바로 프론트 팀도 이 URL 기준으로 개발 들어가는 거야.

 

👉 필요 API 설계

1. 회원가입 (Signup)

• 설명: 사용자 회원가입 처리
• HTTP 메서드: POST /api/signup/

▶️ Request Body:

{
  "email": "user@example.com",
  "password": "password123",
  "nickname": "닉네임",
  "name": "홍길동",
  "phone_number": "010-1234-5678"
}

▶️ Response:

{
  "message": "회원가입이 완료되었습니다.",
  "user_id": 1
}

---

2. 로그인 (Login)

• 설명: JWT 토큰 발급
• HTTP 메서드: POST /api/token/

▶️ Request Body:

{
  "email": "user@example.com",
  "password": "password123"
}

▶️ Response:

{
  "access": "jwt-access-token",
  "refresh": "jwt-refresh-token"
}

---

3. 내 정보 조회 (My Profile)

• 설명: 로그인 사용자 정보 조회
• HTTP 메서드: GET /api/users/me/

▶️ Response:

{
  "id": 1,
  "email": "user@example.com",
  "nickname": "닉네임",
  "name": "홍길동",
  "phone_number": "010-1234-5678",
  "date_joined": "2025-06-09T12:00:00Z"
}

🔐 Access Token 필요

---

4. 내 정보 수정 (Update Profile)

• 설명: 로그인 사용자 정보 수정
• HTTP 메서드: PATCH /api/users/me/

▶️ Request Body:

{
  "nickname": "새로운 닉네임",
  "phone_number": "010-9876-5432"
}

▶️ Response:

{
  "message": "회원 정보가 수정되었습니다."
}

---

💰 Account API

5. 계좌 목록 조회 (List Accounts)

• 설명: 사용자 계좌 목록 조회
• HTTP 메서드: GET /api/accounts/

▶️ Response:

[
  {
    "id": 1,
    "account_number": "123-456-789",
    "bank_code": "004",
    "account_type": "자동인출",
    "balance": "100000.00",
    "created_at": "2025-06-09T12:00:00Z"
  }
]

---

6. 계좌 생성 (Create Account)

• 설명: 새 계좌 생성
• HTTP 메서드: POST /api/accounts/

▶️ Request Body:

{
  "account_number": "987-654-321",
  "bank_code": "004",
  "account_type": "준비금"
}

▶️ Response:

{
  "message": "계좌가 성공적으로 생성되었습니다.",
  "account_id": 2
}

---

💳 Transaction API

7. 결제내역 목록 조회 (List Transactions)

• 설명: 계좌 결제 내역 조회
• HTTP 메서드: GET /api/accounts/<int:account_id>/transactions/

▶️ Response:

[
  {
    "id": 1,
    "transaction_amount": "50000.00",
    "post_transaction_amount": "150000.00",
    "transaction_details": "급여",
    "transaction_type": "입금",
    "transaction_method": "이체거래",
    "transaction_timestamp": "2025-06-08T14:00:00Z"
  }
]

---

8. 결제내역 생성 (Create Transaction)

• 설명: 계좌에 결제 내역 추가
• HTTP 메서드: POST /api/accounts/<int:account_id>/transactions/

▶️ Request Body:

{
  "transaction_amount": "30000.00",
  "transaction_details": "ATM 인출",
  "transaction_type": "출금",
  "transaction_method": "ATM",
  "transaction_timestamp": "2025-06-09T15:30:00Z"
}

▶️ Response:

{
  "message": "결제 내역이 성공적으로 추가되었습니다.",
  "transaction_id": 5
}

---

📅 기본 ERD

User (CustomUser)
    └── Account (1:N)
           └── TransactionHistory (1:N)

---