오늘은 우리가 매일 만드는 API, 그중에서도 API 설계 원칙에 대해 이야기해볼게. 이론 책에 나오는 뻔한 이야기 말고, 내가 12년 동안 백엔드 개발을 하면서 깨달은 실무 중심의 팁을 전해주고 싶거든. API를 어떻게 설계하느냐에 따라 프론트엔드 개발자와의 협업 효율이 하늘과 땅 차이로 갈리니까 집중해서 읽어봐.
1. 자원(Resource)과 행위(Method)를 명확히 분리하자
가장 기본적이면서도 의외로 많은 신입들이 실수하는 부분이야. API 주소(URI)에는 오직 명사형 자원만 두고, 어떤 행동을 할지는 HTTP Method(GET, POST, PUT, DELETE)에 맡겨야 해.
- 나쁜 예시:
POST /get-user-info,POST /delete-user - 좋은 예시:
GET /users/1,DELETE /users/1URI에delete나show같은 동사를 넣는 순간RESTful한 구조가 깨지기 시작해. URL은 자원의 위치를 나타내는 이정표고, 행위는 Method로 표현하는 게 약속이거든. 이 약속만 잘 지켜도 API 가독성이 확 올라가.
2. 예측 가능한 일관성을 유지하자
실무에서 좋은 API의 핵심은 **일관성(Consistency)**이야. 요청(Request)과 응답(Response)의 데이터 구조가 API마다 제각각이면 쓰는 사람 입장에서 정말 고통스럽거든.
- 에러 포맷 통일: 에러가 발생했을 때 반환하는 JSON 구조를 하나로 통일해봐. 예외 응답에는 항상
errorCode와errorMessage가 일관되게 들어가야 프론트엔드에서 공통 에러 핸들러를 만들기 편해. - HTTP 상태 코드 활용: 무조건
200 OK로 보내고 바디에success: false를 담는 방식은 피하는 게 좋아. 인증 실패는401 Unauthorized, 권한 없음은403 Forbidden, 잘못된 요청은400 Bad Request처럼 표준 HTTP Status Code를 적절히 활용하는 게 훨씬 직관적이야.
3. 실용주의가 이론을 이긴다
학계나 책에서는 REST API의 최고 단계로 HATEOAS(Hypermedia As The Engine Of Application State)를 강조하곤 해. 응답 데이터에 다음 단계로 이동할 수 있는 링크들을 다 담아주는 방식이지. 하지만 솔직히 말할게. 내가 12년 동안 일하면서 이거 제대로 쓰는 프로젝트 거의 못 봤어.
- 실용적 설계: 이론적인 완벽함에 집착하다가 마감 기한을 놓치는 것보다, 직관적이고 사용하기 편한 API를 빠르게 제공하는 게 훨씬 나아.
- 버전 관리: 실무에서는 비즈니스 요구사항에 따라 API가 계속 변하거든. 처음부터
/api/v1/users처럼 URI에 버전을 명시해두는 습관을 들여봐. 나중에 기능이 크게 바뀔 때 하위 호환성을 유지하기가 훨씬 쉬워질 거야.
💡 핵심 정리
- URI에는 명사(자원)만 사용하고, 행위는
GET,POST같은 HTTP Method로 표현하자.- 에러 포맷을 통일하고 적절한 HTTP 상태 코드를 반환하여 예측 가능한 API를 만들자.
HATEOAS같은 과한 이론에 집착하기보다v1/버전 관리 같은 실용적인 규칙을 먼저 적용하자. API는 결국 다른 개발자와 나누는 소통의 도구이자 계약서야. 이 계약서가 명확하고 예측 가능할수록 불필요한 의사소통 비용이 줄어들고 전체적인 개발 속도가 빨라지거든. 오늘 이야기한 기본 원칙들을 네 프로젝트에 바로 적용해봐. 훨씬 더 단단한 백엔드 아키텍처를 가질 수 있을 거야. 항상 응원한다!