1. REST API 문서

1. 개요

1-1. 문서 설명

• ✅ 작업 완료
• 🛠 작업 중

1-2. 주요 상태 코드

HTTP 상태코드	설명
200 OK	서버가 클라이언트의 요청을 성공적으로 수행하였음을 의미합니다. 응답 바디의 경우 각 API별로 응답 바디의 형식이 다를 수 있으므로, 자세한 내용은 각 API별 상세 설명을 참고합니다.
201 Created	서버가 클라이언트의 요청을 성공적으로 수행 후 리소스가 생성되었음을 의미합니다.
400 Bad Request	서버가 클라이언트 오류(잘못된 요청 구문 등)를 감지해 요청을 처리할 수 없거나, 하지 않는다는 것을 의미합니다.
401 Unauthorized	클라이언트 오류 상태 응답 코드는 해당 리소스에 유효한 인증 자격 증명이 없기 때문에 요청이 수행되지 않았음을 나타냅니다.
403 Forbidden	서버에 요청이 전달되었지만, 권한 때문에 거절되었음을 의미합니다.
500 Internal Server Error	요청을 처리하는 과정에서 서버가 예상하지 못한 상황에 놓였다는 것을 나타냅니다.

1-3. 서버 에러 코드

에러 코드	설명	HTTP 상태 코드
E-001	설명1	400
E-002	설명2	403
E-003	설명3	409

1-4. 오류 응답 형식

Name	Type	Description
code	string	서버 에러 코드
message	string	에러 내용
instance	string	에러 발생 근원지 URL

오류 응답 형식 예시

{
  "code": "E-001",
  "message": "고양이 이미지 업로드 실패",
  "instance": "POST /cats"
}

2. REST API

2-1. 인증

✅ 로그인 및 회원가입

• 사용자의 지역 정보와 함께 Kakao 로그인 요청을 보낸 후 JWT 토큰(access token, refresh token)(사용자 정보)를 받는다.

Request URL

GET /kakao

Request 예시

GET /kakao

Response Headers Cookies

Name	Type	Description	Required
x-auth-cookie	string	access token 입니다.	O
x-auth-cookie-refresh	string	refresh token 입니다.	O

Response 예시

1. 로그인 성공

HTTP/1.1 302 Ok
Content-Type: application/json
Cookie: x-auth-cookie=this-is-access-token; x-auth-cookie-refresh=this-is-refresh-token

✅ KaKao 콜백

• /kakao 접근에 대한 콜백

Request URL

GET /kakao/callback

Request 예시

GET /kakao/callback

Response 예시

1. 콜백 성공

HTTP/1.1 200 Ok
Content-Type: application/json
Cookie: x-auth-cookie=this-is-access-token; x-auth-cookie-refresh=this-is-refresh-token

✅ refresh token 재발급

• 유저의 access token과 refresh token이 모두 만료되는 경우 재발급을 받습니다.

Request URL

GET /refresh

Request Headers Cookies

Name	Type	Description	Required
x-auth-cookie	string	access token 입니다.	O
x-auth-cookie-refresh	string	refresh token 입니다.	O

Request 예시

GET /refresh

Content-Type: application/json
Cookie: x-auth-cookie=this-is-access-token; x-auth-cookie-refresh=this-is-refresh-token

Response Body

Name	Type	Description	Required
accessToken	string	access token 입니다.	O
refreshToken	string	refresh token 입니다	O

Response 예시

1. 로그인 성공

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "accessToken": "this-is-access-token",
  "refreshToken": "this-is-refresh-token"
}

✅ @Deprecated 로그인 (기존 로그인)

• 하위 호환을 위해 route는 유지 합니다.
• 사용자의 지역 정보와 함께 로그인 요청을 보낸 후 사용자 정보를 받는다.

Request URL

GET /login

Request Query Parmeter

Name	Type	Description	Required
location	string	사용자의 지역	O

Request 예시

GET /login?location=gangnamgu

Response Body

Name	Type	Description	Required
id	number	사용자 DB 아이디	O
name	string	사용자 이름	O
location	string	사용자의 지역	O

Response 예시

1. 로그인 성공

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "id": 2,
  "name": "Nyang1"
}

2-2. Cat

✅ 특정 지역의 모든 고양이 조회

• 특정 지역의 모든 고양이 정보를 조회한다.

Request URL

GET /cats
Authorization: userId={사용자 DB 아이디}

Request Query Parameter

Name	Description	Required
location	고양이 조회할 지역명	O

Response Body(Array)

Name	Type	Description	Required
id	number	고양이 DB 아이디	O
position	Position	고양이 위치	O

• Position

Name	Type	Description	Required
latitude	number	고양이 위치의 위도 값	O
longitude	number	고양이 위치의 경도 값	O

Response 예시

1. 조회 성공

HTTP/1.1 200 Ok
Content-Type: application/json
[
  {
    "id": 1,
    "latitude": 123;
    "longitude": 123;
    "imageUrl": "http://xxx.xxx.xxx.xxx:3000/images/xxx.jpg";
    "_count": {
       "likes": 123
    };
  },
  {
    "id": 2,
    "latitude": 123;
    "longitude": 123;
    "imageUrl": "http://xxx.xxx.xxx.xxx:3000/images/xxx.jpg";
    "_count": {
       "likes": 50
    };
  },
  {...}
]

✅ 특정 고양이 조회

• 특정 고양이 정보를 조회한다.

Request URL

GET /cats/:id
Authorization: userId={사용자 DB 아이디}

Response Body

Name	Type	Description	Required
id	number	고양이 DB 아이디	O
description	string	고양이에 대한 설명	O
image	string	고양이 이미지 URL	O
address	string	고양이 지역	O
likes	number	고양이의 좋아요 수	O
isLiked	boolean	사용자가 좋아요를 눌렀는지 여부	O

Response Body 예시

1. 조회 성공

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "id": 1,
  "description": "커여움",
  "image": "http://xxx.xxx.xxx.xxx:3000/xxx.jpg",
  "address": "강남구",
  "_count": {
       "likes": 123
   };
   // "likes": 123,  // @Deprecated
  "isLiked": true
}

✅ 고양이 등록

• 서비스에 새로운 고양이를 등록한다.

Request URL

POST /cats
Authorization: userId={사용자 DB 아이디}
Content-Type: multipart/form-data

Request Body

Name	Type	Description	Required
catImage	binary	업로드할 이미지 파일 바이너리 MIME 타입은 image/jpeg, image/jpg, image/png만 가능	O
description	string	이미지에 대한 설명	O
location	string	고양이 주소	O
latitude	number	고양이 위치의 위도 값	O
longitude	number	고양이 위치의 경도 값	O

Response Body

Name	Type	Description	Required
id	number	등록된 고양이 DB 아이디	O

Response Body 예시

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 23
}

@Deprecated 위의 GET /cats으로 통일.

### 🛠 우리동네 짱고양이 랭킹 조회

• 사용자 지역의 고양이 랭킹 정보를 조회한다.

Request URL

GET /cats/rank
Authorization: userId={사용자 DB 아이디}

Response Body(Array)

Name	Type	Description	Required
id	number	등록된 고양이 DB 아이디	O
image	string	고양이 이미지 URL	O
likes	number	고양이의 좋아요 수	O

Response Body 예시

[
  {
    "id": 1,
    "image": "http://xxx.xxx.xxx.xxx:3000/xxx.jpg",
    "likes": 123,
  },
  {
    "id": 2,
    "imageUrl": "http://xxx.xxx.xxx.xxx:3000/images/yyy.jpg",
    "likes": 456,
  },
  {...}
]