friend request

[seokulee]

API 명세

개요

friendship 서비스는 사용자들이 친구 관계를 관리할 수 있도록 지원하는 RESTful API를 제공합니다. 주요 기능은 다음과 같습니다:

• 친구 요청 전송
• 친구 요청 수락 및 거절
• 친구 삭제
• 친구 목록 조회
• 받은 친구 요청 목록 조회

---

인증 및 권한

• 모든 엔드포인트는 JWT(JSON Web Token)를 사용한 인증이 필요합니다.
• 요청 헤더에 Authorization: Bearer <JWT 토큰>을 포함해야 합니다.
• 인증되지 않은 요청은 401 Unauthorized 상태 코드로 응답됩니다.

---

API 엔드포인트

1. 친구 요청 전송

• URL: /api/friends/request/
• 메서드: POST
• 설명: 지정된 사용자에게 친구 요청을 보냅니다.

요청 헤더

헤더	값	필수
Authorization	Bearer <JWT 토큰>	예
Content-Type	application/json	예

요청 바디

{
    "receiver_id": "<int>" 
}

• receiver_id (int): 친구 요청을 받을 사용자의 ID

응답

• 성공 (201 Created):

  {   
  "message": "Friend request sent successfully." 
  }

• 에러 응답 예시:

  • 이미 친구 요청을 보낸 경우 (400 Bad Request):

      {
          "error": "Friend request already sent."
      }

  • 자신에게 친구 요청을 보내는 경우 (400 Bad Request):

      {
           "error": "You cannot send a friend request to yourself."
      }

  • 대상 사용자가 존재하지 않는 경우 (404 Not Found):

      {
          "error": "Receiver user does not exist."
      }

예시

POST /api/friends/request/ Authorization: Bearer eyJ0eXAiOiJKV1QiLCJh...  {   "receiver_id": 2 }

---

2. 친구 요청 수락

• URL: /api/friends/accept/
• 메서드: POST
• 설명: 받은 친구 요청을 수락합니다.

요청 헤더

헤더	값	필수
Authorization	Bearer <JWT 토큰>	예
Content-Type	application/json	예

요청 바디

{
    "requester_id": "<int>" 
}

• requester_id (int): 친구 요청을 보낸 사용자의 ID

응답

• 성공 (200 OK):

  {   
  "message": "Friend request accepted."
  }

• 에러 응답 예시:

  • 친구 요청이 없는 경우 (404 Not Found):

          {
              "error": "No pending friend request found."
          }

---

3. 친구 요청 거절

• URL: /api/friends/reject/
• 메서드: POST
• 설명: 받은 친구 요청을 거절합니다.

요청 헤더

헤더	값	필수
Authorization	Bearer <JWT 토큰>	예
Content-Type	application/json	예

요청 바디

{ "requester_id": "<int>" }

• requester_id (int): 친구 요청을 보낸 사용자의 ID

응답

• 성공 (200 OK): { "message": "Friend request rejected." }

• 에러 응답 예시:

  • 친구 요청이 없는 경우 (404 Not Found): { "error": "No pending friend request found." }

---

4. 친구 삭제

• URL: /api/friends/remove/
• 메서드: DELETE
• 설명: 친구 관계를 삭제합니다.

요청 헤더

헤더	값	필수
Authorization	Bearer <JWT 토큰>	예
Content-Type	application/json	예

요청 바디

{ "friend_id": "<int>" }

• friend_id (int): 삭제할 친구의 사용자 ID

응답

• **성공 (200 OK): { "message": "Friend removed successfully." }

• 에러 응답 예시:

  • 친구 관계가 없는 경우 (404 Not Found): { "error": "Friend relationship not found." }

`

---

5. 친구 목록 조회

• URL: /api/friends/
• 메서드: GET
• 설명: 현재 사용자의 친구 목록을 조회합니다.

요청 헤더

헤더	값	필수
Authorization	Bearer <JWT 토큰>	예

응답

• 성공 (200 OK): [ { "id": 2, "username": "friend_username", "email": "friend@example.com", "profile_image": "https://example.com/profile.jpg" }, { "id": 3, "username": "another_friend", "email": "another@example.com", "profile_image": "https://example.com/profile2.jpg" } // ... ]

• 에러 응답 예시:

  • 인증되지 않은 경우 (401 Unauthorized): { "detail": "Authentication credentials were not provided." }

---

6. 받은 친구 요청 목록 조회

• URL: /api/friends/requests/
• 메서드: GET
• 설명: 현재 사용자가 받은 친구 요청 목록을 조회합니다.

요청 헤더

헤더	값	필수
Authorization	Bearer <JWT 토큰>	예

응답

• 성공 (200 OK): [ { "id": 1, "username": "requester_username", "email": "requester@example.com", "profile_image": "https://example.com/profile.jpg" }, // ... ]

• 에러 응답 예시:

  • 인증되지 않은 경우 (401 Unauthorized): { "detail": "Authentication credentials were not provided." }

---

HTTP 상태 코드

• 200 OK: 요청이 성공적으로 처리되었음
• 201 Created: 리소스가 성공적으로 생성되었음
• 400 Bad Request: 잘못된 요청 (필수 필드 누락, 유효하지 않은 데이터 등)
• 401 Unauthorized: 인증 실패 (토큰 누락 또는 유효하지 않은 토큰)
• 403 Forbidden: 권한 없음 (해당 작업을 수행할 권한이 없음)
• 404 Not Found: 리소스를 찾을 수 없음 (존재하지 않는 사용자 또는 친구 관계 등)
• 503 Service Unavailable: 서비스 이용 불가 (외부 서비스 호출 실패 등)

---

참고 사항

• 외부 서비스 호출: 친구 목록 조회 및 친구 요청 수락/거절 시 Authentication_app의 API를 호출하여 사용자 정보를 가져옵니다.
• 타임아웃 설정: 외부 서비스 호출 시 타임아웃을 설정하여 응답 지연을 방지합니다.
• 에러 처리: 외부 서비스 호출 실패 시 적절한 에러 메시지를 반환합니다.
• 데이터 타입: 모든 ID 필드는 정수형이어야 합니다.
• 데이터 검증: 모든 입력 데이터에 대해 유효성 검사를 수행합니다.

---

엔드포인트 요약표

기능	메서드	URL	설명
친구 요청 전송	POST	/api/friends/request/	지정된 사용자에게 친구 요청 보냄
친구 요청 수락	POST	/api/friends/accept/	받은 친구 요청을 수락
친구 요청 거절	POST	/api/friends/reject/	받은 친구 요청을 거절
친구 삭제	DELETE	/api/friends/remove/	친구 관계를 삭제
친구 목록 조회	GET	/api/friends/	친구 목록을 조회
받은 친구 요청 목록 조회	GET	/api/friends/requests/	받은 친구 요청 목록을 조회