🗂️ API 명세서

API 명세란?

백엔드가 어떤 경로(Endpoint)를 제공하고, 어떤 방식(Method)으로 요청해야 하며, 요청/응답에 어떤 데이터를 주고받는지를 문서화한 것이다.

API 명세서 내용

1. 🔗Endpoint (URL 경로)

API를 어떤 주소로 요청할지 결정한다. 여러 API를 구분하는 식별자 역할을 한다.
예: /users, /posts/1, /login

예시:

GET /users
POST /login
DELETE /posts/{id}

2. 📮HTTP Method (요청 방식)

요청을 어떻게 처리할지 의미하는 키워드이다.

Method	설명
GET	정보 조회
POST	새로운 데이터 생성
PUT	전체 수정
PATCH	부분 수정
DELETE	데이터 삭제

예시:

POST /login → 로그인 요청
GET /users → 유저 목록 조회

3. 📥Request Parameters (요청 데이터)

프론트엔드가 백엔드로 보낼 데이터들을 의미한다.

종류	위치	설명	예시
Path Parameter	URL 안	값이 URL에 포함됨	/users/{id}
Query Parameter	?key=value	필터링/검색용	/posts?userId=3
Request Body	body에 담김	POST/PUT에 주로 사용	{ "title": "제목" }
Header	메타 정보	인증 토큰, 언어 설정 등	Authorization: Bearer token

예시:

POST /login
Body:
{
  "email": "test@email.com",
  "password": "1234"
}

4. 📤Response (응답 데이터)

백엔드가 프론트에 보내는 데이터이다.

요소	설명	예시
Status Code	요청 처리 결과 숫자	200, 400, 404, 500
Response Body	실제 전달되는 데이터	{ "name": "홍길동" }

예시:

200 OK
{
  "id": 1,
  "name": "홍길동",
  "email": "hong@example.com"
}

5. ⚠️Error Cases (에러 상황 정의)

실패했을 때 어떤 에러가 나는지에 대한 정의이다.

Status Code	의미	예시 메시지
400	잘못된 요청	"필수값 누락"
401	인증 실패	"로그인이 필요합니다"
403	권한 없음	"접근 불가"
404	존재하지 않음	"사용자를 찾을 수 없습니다"
500	서버 오류	"내부 서버 오류"

6. 🧾예시 요청 및 응답 (Example)

실제 사용할 때 어떤 식으로 요청하고 어떤 응답이 오는지 보여주는 샘플이다.

예시:

POST /login

요청:
{
  "email": "kim@test.com",
  "password": "1234"
}

응답:
{
  "accessToken": "abcdef12345",
  "userId": 7
}