API 문서 작성

[mtak0235]

REST API 명세

1. 사용자 관리 API

1.1 회원가입

• URL: POST /api/users

• Request Body:

  json
  
  Copy
  
  {
  "username": "string",
  "email": "string",
  "password": "string",
  "userType": "BUYER | KEEPER"
  }

• Response: 201 Created

  json
  
  Copy
  
  {
  "id": "long",
  "username": "string",
  "email": "string",
  "userType": "BUYER | KEEPER"
  }

1.2 로그인

• URL: POST /api/auth/login

• Request Body:

  json
  
  Copy
  
  {
  "email": "string",
  "password": "string"
  }

• Response: 200 OK

  json
  
  Copy
  
  {
  "token": "string",
  "userId": "long"
  }

2. 보관 공간 API

2.1 보관 공간 등록

• URL: POST /api/storage-spaces

• Headers: Authorization: Bearer {token}

• Request Body:

  json
  
  Copy
  
  {
  "spaceType": "REFRIGERATOR | FREEZER | ROOM_TEMPERATURE",
  "capacity": "int",
  "photos": ["string"],
  "maxDeposit": "decimal",
  "tags": ["string"],
  "dailyRate": "decimal"
  }

• Response: 201 Created

  json
  
  Copy
  
  {
  "id": "long",
  "ownerId": "long",
  "spaceType": "REFRIGERATOR | FREEZER | ROOM_TEMPERATURE",
  "capacity": "int",
  "photos": ["string"],
  "maxDeposit": "decimal",
  "tags": ["string"],
  "dailyRate": "decimal"
  }

2.2 보관 공간 검색

• URL: GET /api/storage-spaces

• Query Parameters:

  • spaceType: REFRIGERATOR | FREEZER | ROOM_TEMPERATURE
  • minCapacity: int
  • maxDailyRate: decimal
  • tags: string (comma-separated)

• Response: 200 OK

  json
  
  Copy
  
  {
  "content": [
    {
      "id": "long",
      "ownerId": "long",
      "spaceType": "REFRIGERATOR | FREEZER | ROOM_TEMPERATURE",
      "capacity": "int",
      "photos": ["string"],
      "maxDeposit": "decimal",
      "tags": ["string"],
      "dailyRate": "decimal"
    }
  ],
  "pageable": {
    "pageNumber": "int",
    "pageSize": "int",
    "sort": ["string"]
  },
  "totalElements": "long",
  "totalPages": "int"
  }

3. 보관 요청 API

3.1 보관 요청 생성

• URL: POST /api/storage-requests

• Headers: Authorization: Bearer {token}

• Request Body:

  json
  
  Copy
  
  {
  "itemDescription": "string",
  "spaceType": "REFRIGERATOR | FREEZER | ROOM_TEMPERATURE",
  "requiredCapacity": "int",
  "startDate": "date",
  "endDate": "date"
  }

• Response: 201 Created

  json
  
  Copy
  
  {
  "id": "long",
  "requesterId": "long",
  "itemDescription": "string",
  "spaceType": "REFRIGERATOR | FREEZER | ROOM_TEMPERATURE",
  "requiredCapacity": "int",
  "startDate": "date",
  "endDate": "date",
  "status": "PENDING"
  }

3.2 보관 요청 수락

• URL: PUT /api/storage-requests/{requestId}/accept

• Headers: Authorization: Bearer {token}

• Response: 200 OK

  json
  
  Copy
  
  {
  "id": "long",
  "requesterId": "long",
  "keeperId": "long",
  "itemDescription": "string",
  "spaceType": "REFRIGERATOR | FREEZER | ROOM_TEMPERATURE",
  "requiredCapacity": "int",
  "startDate": "date",
  "endDate": "date",
  "status": "ACCEPTED"
  }

4. 결제 및 보증금 API

4.1 결제 생성

• URL: POST /api/payments

• Headers: Authorization: Bearer {token}

• Request Body:

  json
  
  Copy
  
  {
  "storageRequestId": "long",
  "amount": "decimal"
  }

• Response: 201 Created

  json
  
  Copy
  
  {
  "id": "long",
  "storageRequestId": "long",
  "payerId": "long",
  "receiverId": "long",
  "amount": "decimal",
  "status": "PENDING"
  }

4.2 보증금 설정

• URL: POST /api/deposits

• Headers: Authorization: Bearer {token}

• Request Body:

  json
  
  Copy
  
  {
  "storageRequestId": "long",
  "amount": "decimal"
  }

• Response: 201 Created

  json
  
  Copy
  
  {
  "id": "long",
  "storageRequestId": "long",
  "userId": "long",
  "amount": "decimal",
  "status": "HELD"
  }

공통 에러 응답 형식

모든 API는 오류 발생 시 다음과 같은 형식으로 응답합니다:

• Response: 4xx/5xx Status Code

  json
  
  Copy
  
  {
  "timestamp": "ISO-8601 format",
  "status": "int",
  "error": "string",
  "message": "string",
  "path": "string"
  }

주요 에러 코드

• 400 Bad Request: 잘못된 요청 (예: 유효하지 않은 입력값)
• 401 Unauthorized: 인증 실패
• 403 Forbidden: 권한 없음
• 404 Not Found: 리소스를 찾을 수 없음
• 409 Conflict: 리소스 충돌 (예: 중복된 사용자명)
• 422 Unprocessable Entity: 유효성 검사 실패
• 500 Internal Server Error: 서버 내부 오류

API별 주요 예외 사항

1. 사용자 관리 API

1.1 회원가입

• 409 Conflict: 이미 존재하는 이메일 또는 사용자명
• 422 Unprocessable Entity: 유효하지 않은 이메일 형식 또는 비밀번호 요구사항 불충족

1.2 로그인

• 401 Unauthorized: 잘못된 이메일 또는 비밀번호

2. 보관 공간 API

2.1 보관 공간 등록

• 400 Bad Request: 유효하지 않은 공간 유형 또는 용량
• 403 Forbidden: KEEPER 권한이 없는 사용자

2.2 보관 공간 검색

• 400 Bad Request: 유효하지 않은 검색 조건

3. 보관 요청 API

3.1 보관 요청 생성

• 400 Bad Request: 유효하지 않은 날짜 범위 또는 용량
• 403 Forbidden: BUYER 권한이 없는 사용자

3.2 보관 요청 수락

• 404 Not Found: 존재하지 않는 보관 요청
• 409 Conflict: 이미 수락된 보관 요청

4. 결제 및 보증금 API

4.1 결제 생성

• 400 Bad Request: 유효하지 않은 금액
• 404 Not Found: 존재하지 않는 보관 요청
• 409 Conflict: 이미 결제된 보관 요청

4.2 보증금 설정

• 400 Bad Request: 유효하지 않은 보증금 금액
• 404 Not Found: 존재하지 않는 보관 요청
• 409 Conflict: 이미 보증금이 설정된 보관 요청

[mtak0235]

TODO: Spring RestDocs로 관리