📝 API는 왜 이렇게 많고 복잡할까? 좋은 API 설계의 기준은?

 

서비스를 개발하다 보면 한 번쯤 이런 생각을 해보셨을 겁니다.

“API가 왜 이렇게 많고 복잡하지?”
“그냥 한 줄로 끝내면 안 돼?”

 

그런데 놀랍게도, 이 복잡함이 오히려 좋은 API의 핵심입니다.
오늘은 좋은 API란 무엇인지, 그리고 왜 '많고 복잡한 게' 꼭 나쁜 건 아닌지 이야기해보겠습니다.

---

🔍 API는 왜 복잡할까?

API는 단순한 함수 호출이 아닙니다.
그건 두 시스템 간의 약속이고, 언어이자 인터페이스입니다.

예를 들어:

• 프론트와 백엔드를 연결하고
• 앱과 서버를 연결하며
• 외부 서비스(Google, Kakao 등)와 통신하기도 합니다

이처럼 다양한 상황과 역할을 수행해야 하다 보니,

• API는 많아지고
• 상황마다 요구사항도 달라지고
• 결과 구조도 다양해질 수밖에 없습니다

---

✅ 좋은 API의 기준은?

그렇다면 좋은 API는 어떤 모습일까요?
사실 정답은 아주 심플합니다.

"예측 가능하고, 일관된 것."

API는 결국 개발자가 쉽게 이해하고,
문제가 생겼을 때 빠르게 대응할 수 있도록 도와주는 **‘배려의 인터페이스’**여야 합니다.

---

📌 1. 명확한 HTTP 메서드 사용

메서드역할

GET	데이터 조회
POST	데이터 생성
PUT/PATCH	데이터 수정
DELETE	데이터 삭제

 

✅ 예: GET /users/123 → 사용자 정보 조회
❌ 예: POST /getUserInfo → 이름만 봐선 뭐 하는 API인지 모름

---

📌 2. 일관된 URL 설계

• RESTful한 구조 사용: /users/123/posts
• 명사 기반 URL (동사보다 객체 중심)
• 리소스를 기준으로 계층적으로 표현

---

📌 3. 표준 응답 형식 유지

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123,
    "name": "Alice"
  }
}

 

항상 code, message, data 형식을 유지하면
클라이언트 측에서도 파싱, 에러 핸들링이 쉬워집니다.

---

📌 4. 정확한 상태 코드 사용

상태 코드의미

200	OK (성공)
201	Created (생성 성공)
400	Bad Request (잘못된 요청)
404	Not Found (리소스 없음)
500	Internal Server Error (서버 오류)

 

무조건 200만 주지 말고, 상황에 맞는 코드를 줘야 클라이언트도 대응할 수 있습니다.

---

📌 5. 문서화는 필수입니다

• Swagger (OpenAPI 기반)
• Postman Collection

✅ 누구나 쉽게 테스트하고 이해할 수 있도록
자동 문서화 or 예제 중심 문서는 꼭 필요합니다.

---

🌟 좋은 API 예시

🔐 Kakao 로그인 API

• OAuth2 흐름에 맞춘 깔끔한 URL
• 파라미터 설명이 명확
• 에러 케이스까지 상세히 문서화됨
  → "신뢰감 있는 문서"의 모범

---

💳 Stripe 결제 API

• /v1/... 방식의 철저한 버전 관리
• 실패 케이스를 포함한 다양한 예제 제공
• OpenAPI 기반 명세 제공
  → "실전에서 바로 써먹을 수 있는 API"

---

🛠 GitHub REST API

• CRUD 기능을 RESTful하게 표현
• 헤더, 캐시 정책, 상태 코드까지 문서화
• curl 예제도 함께 제공
  → "개발자 친화적인 API 설계"

---

⚠️ 흔한 API 설계 실수

실수설명

동사 기반 URL	/getUserInfo → REST 원칙 위반
상태 코드 무시	항상 200 OK만 반환하면 오류 파악 어려움
버전 관리 없음	구조 변경 시 앱 전체가 깨질 수 있음
응답 구조 불일치	어떤 API는 result, 어떤 건 response… 혼란 유발

 

---

🧭 마무리: 좋은 API는 “배려”입니다

좋은 API는 단순히 “잘 작동하는” API가 아닙니다.

✅ 예측 가능하고
✅ 일관되며
✅ 명확하게 커뮤니케이션할 수 있는 API

바로 그런 API가 좋은 API입니다.

---

API 설계는 기술이 아니라, 커뮤니케이션입니다.
결국, 코드를 짜는 다른 개발자를 위한 배려의 결정체죠.