웹 서비스 개발 – API 개발 기초 – 2 – API 문서 작성 (Swagger, OpenAPI 등)

작성자 wooah
웹 서비스 개발 - API 개발 기초 - 2 - API 문서 작성 (Swagger, OpenAPI 등)
웹 서비스 개발 – API 개발 기초 – 2 – API 문서 작성 (Swagger, OpenAPI 등)

웹 서비스 개발 – API 개발 기초 – API 설계 원칙

안녕하세요, 여러분~ 😊
이번 시간에는 API 개발에서 가장 중요한 기초 체력!
바로 **”API 설계 원칙”**에 대해 이야기해보려고 해요.

아무리 기능이 많고 성능이 뛰어난 API라도,
잘 설계되지 않으면 유지보수와 협업, 확장성이 매우 어려워진답니다.
예쁜 건물도 설계도면이 좋아야 튼튼하게 올라가듯이,
API도 명확하고 일관된 설계가 핵심이에요!

1. URI는 자원(Resource)을 표현해야 해요

RESTful API의 핵심은 자원 중심 설계입니다.
URI는 명사 중심으로 설계해야 하고, 동사는 사용하지 않는 게 원칙이에요.

❌ 잘못된 예시

/getUser
/createUser
/deleteUser?id=5

✅ 올바른 예시

/users
/users/5
  • /users → 사용자 리스트 조회
  • /users/5 → ID가 5인 사용자 조회

URI는 “무엇을” 다루는지 명확하게 표현해주는 것이 중요해요!
동사는 HTTP 메서드로 표현하면 됩니다.

2. HTTP 메서드에 맞는 동작 구분하기

API의 행위는 HTTP 메서드로 구분해야 합니다.

메서드 역할 예시
GET 데이터 조회 /users, /users/5
POST 새 데이터 생성 /users
PUT 전체 수정 /users/5
PATCH 부분 수정 /users/5
DELETE 삭제 /users/5

예시

  • GET /products → 상품 목록 조회
  • POST /products → 상품 등록
  • DELETE /products/10 → 10번 상품 삭제

메서드를 정확히 구분하면 문서 없이도 API가 명확해져요!

3. 일관된 응답 포맷을 사용하기

응답 데이터는 항상 일정한 구조를 유지해야 합니다.
대부분 JSON 포맷을 사용하며, 성공/실패 여부를 명확히 해야 해요.

✅ 성공 응답 예시

{
  "status": "success",
  "data": {
    "id": 5,
    "name": "홍길동",
    "email": "gildong@example.com"
  }
}

❌ 실패 응답 예시

{
  "status": "error",
  "message": "해당 사용자를 찾을 수 없습니다.",
  "code": 404
}

프론트엔드에서 파싱하기 쉽게 일관된 구조를 유지하세요.

4. HTTP 상태코드 제대로 사용하기

API는 작업 결과에 맞는 HTTP 상태코드를 반환해야 합니다.

코드 의미 설명
200 OK 요청 성공
201 Created 리소스 생성 성공
204 No Content 응답 데이터 없음
400 Bad Request 잘못된 요청
401 Unauthorized 인증 필요
403 Forbidden 권한 없음
404 Not Found 자원 없음
500 Internal Server Error 서버 오류

상태코드를 보고 바로 상황을 파악할 수 있도록 도와주는 건 개발자의 배려예요!

5. 필터링, 정렬, 페이징 지원하기

목록 데이터를 반환할 땐 필터링, 정렬, 페이지네이션을 함께 제공해야 사용성이 좋아집니다.

예시

GET /products?category=food&sort=price_desc&page=2&limit=10
  • category=food → 필터링
  • sort=price_desc → 정렬
  • page=2&limit=10 → 페이지네이션

데이터를 줄여서 요청하면 성능도 좋아지고 사용자 경험도 향상돼요!

6. 오류 메시지는 상세하게 제공하기

에러가 발생했을 때, 무슨 문제가 있었는지 구체적으로 안내해 주세요.

예시

{
  "status": "error",
  "message": "이메일 형식이 올바르지 않습니다.",
  "errors": {
    "email": "올바른 이메일을 입력하세요."
  }
}

특히 폼 검증, 권한 문제 등은 구체적인 설명이 필수예요!

7. API 버전 명시하기

서비스가 커지면 API 구조도 바뀔 수 있어요.
그래서 버전을 명시하는 습관이 매우 중요합니다.

예시

/v1/users
/v2/users
  • v1은 기존 구조 유지
  • v2는 새 구조 적용

백엔드 API는 한 번 배포되면 수많은 프론트와 앱이 의존하므로, 안정성과 호환성을 고려해야 해요.

8. 인증과 권한은 반드시 처리하기

API는 누구나 호출할 수 있기 때문에, **인증(Authentication)**과 권한(Authorization) 처리가 필수입니다.

대표적인 인증 방식

  • JWT (JSON Web Token): 헤더에 토큰 포함
  • OAuth2: 구글, 카카오 로그인 등에 사용
  • API 키: 외부 파트너 서비스용

민감한 API는 반드시 보호해주세요! 🔐

9. REST 원칙을 따르되, 상황에 따라 융통성 있게!

REST는 분명 훌륭한 구조지만,
실제 현업에서는 프로젝트 특성에 맞춰 유연하게 설계하는 경우도 많아요.

예를 들어:

  • POST /login → 로그인은 행동 중심이므로 예외적으로 동사 사용 허용
  • POST /products/10/like → 비표준이지만 사용자 경험상 유용함

결국 중요한 건 “일관성”과 “명확함”입니다!

주의사항 체크리스트 ✅

항목 주의할 점
URI 명사 사용, 동사 지양
메서드 GET, POST, PUT, DELETE 정확히 구분
응답 포맷 항상 JSON, 일관된 구조 유지
상태코드 의미에 맞게 정확히 설정
에러 메시지 사용자에게 친절하고 구체적으로 안내
인증 민감한 API는 인증 필수
버전 관리 변화가 많을수록 API 버전 명시 필수

마무리하며 😊

이제 여러분은 API를 설계할 때 어떤 점을 중요하게 생각해야 하는지 잘 알게 되셨을 거예요!
코드보다 더 중요한 건 “설계”라는 말이 있듯,
잘 설계된 API는 팀원에게 신뢰를 주고, 사용자에게 만족을 줍니다.

다음 시간에는 RESTful API를 실제로 어떻게 구축하고 테스트하는지 실습 중심으로 배워볼게요!
오늘도 한 걸음 더 성장하는 여러분의 개발 여정을 응원합니다~ 💪🚀💻

감사합니다! 🙌

답글 남기기