[나만무] API 명세 | 엔드포인트 설계, 그리고 소셜 로그인

카테고리

프로그래밍/소프트웨어 개발

서브카테고리

개발 툴

대상자

• *백엔드/프론트엔드 개발자, API 설계자**
• 난이도: 중간 (API 설계/협업 경험자 대상)*

핵심 요약

• API 명세서는 백엔드와 프론트엔드 간 데이터 전송 경로, 형식, 필드 구조를 미리 정의하여 협업 효율성 향상
• 엔드포인트 설계 시 URL + HTTP 메서드 형식으로 명시, Resource-Oriented 방식이 DB 구조와 일관성 유지
• 소셜 로그인은 OAuth 2.0 Authorization Code Grant 방식 사용, POST /api/auth/social/kakao/redirect와 callback 엔드포인트 활용

섹션별 세부 요약

1. API 명세서의 중요성

• 명세서 없이 협업 시 데이터 형식 미스매칭 → 재작업 리스크 증가
• 명세서 포함 항목

- 요청 URL, 메서드, 헤더/파라미터/바디 구조

- 응답 상태 코드(예: 201 Created, 400 Bad Request)

- 에러 처리 방식

• 명세서는 반복 수정 가능 → 팀원 공유 필수

2. 엔드포인트 설계 예시

• 회원가입/로그인 API 예시

- POST /api/auth/signup: username, email, password 필드 포함

- POST /api/auth/login: email, password 입력, JWT 토큰 발급(200 OK)

• 응답 구조

- 성공 시: userId, createdAt 필드 포함

- 실패 시: error, message 필드로 에러 메시지 전달

3. 라우팅 방식 선택

• Resource-Oriented 방식

- POST /api/users/signup과 같은 사용자 중심 경로

- 장점: DB 구조와 일관성 유지

- 단점: 인증 기능 복잡성 증가

• Auth-Focused 방식

- POST /api/auth/login과 같은 인증 전용 경로

- 장점: 인증 로직 분리 → 관리 용이

- 단점: 경로 분산으로 일관성 저하

4. 소셜 로그인 구현 흐름

• OAuth 2.0 Authorization Code Grant 단계

1. 사용자 클릭 → /api/auth/social/kakao/redirect 호출
2. 백엔드 → OAuth 서버 리다이렉트
3. OAuth 서버 → 콜백 URL(/api/auth/social/kakao/callback?code=...) 전달
4. 백엔드: 토큰 교환 후 프론트에 결과 전달

• 보안 고려사항

- 토큰 전달 방식: 쿠키(HttpOnly) 또는 JSON(AJAX) 선택

결론

• API 명세서는 개발 중 변경사항을 반영하고 팀원과 공유하여 책임 범위 명확화
• 소셜 로그인 구현 시 OAuth 2.0을 활용하고, 토큰 전달 방식은 보안성을 최우선으로 고려
• Resource-Oriented 라우팅은 DB 구조와 일관성을 유지하는 데 유리한 선택