RESTful API, 50대의 경험으로 풀어보는 잘 설계된 API의 7+1 원칙
"선배님, 문서에는 `/getUser`라고 되어 있는데 404 에러가 계속 나요!"
"아, 그거 내가 얼마 전에 `/users`로 바꿨어. 문서 수정하는 걸 깜빡했네."
제가 처음 팀 프로젝트에 합류했을 때 겪었던 실화입니다.
반나절을 끙끙대며 제 코드만 들여다봤는데, 원인은 어이없게도 소통의 부재였죠.
50대에 새로운 기술 배우는 것도 벅찬데, 사람 사이의 '규칙 없음'이 발목을 잡으니 정말 답답하더군요.
하지만 몇 번의 프로젝트를 거치며 전쟁 같은 마감일을 겪고 나니 뼈저리게 깨달았습니다.
잘 만든 API 하나는, 단순히 코드를 넘어 팀 전체의 생산성을 좌우하는 '중심축'이라는 사실을요.
오늘은 이론적인 이야기는 싹 걷어내고, 제 삽질의 경험을 바탕으로 '잘 설계된 RESTful API'의 7가지 핵심 원칙과 보너스 팁 하나를, 누구나 이해하기 쉽게 풀어 드리겠습니다.
🚀 API, 그거 그냥 '식당 메뉴판' 아닌가요?
API, REST... 용어부터 너무 어렵게 느껴지시죠?
그냥 '아주 잘 만든 프랜차이즈 식당의 메뉴판'이라고 생각하면 정말 쉽습니다.
엉망인 동네 식당 메뉴판을 떠올려보세요.
'김치찌개'는 '오늘의 메뉴'에 있고, '된장찌개'는 '사이드 메뉴'에 있고, 가격은 물어봐야 알려줍니다.
이런 곳에서는 주문 실수가 잦을 수밖에 없죠. 이게 바로 잘못 설계된 API입니다.
• 손님 (나): 클라이언트 (웹브라우저, 앱)
• 주방: 서버 (데이터와 로직이 있는 곳)
• 메뉴판: API (서버와 소통하기 위한 규칙 모음)
• 주문: 요청 (Request)
• 음식: 응답 (Response)
이때 'RESTful' 하다는 건, 이 메뉴판이 전 세계 어느 지점에 가도 똑같은, 누가 봐도 이해하기 쉽고 체계적인 규칙으로 만들어졌다는 의미예요.
메뉴판이 훌륭하면 주문도 정확해지고, 모두가 만족스러운 식사를 할 수 있겠죠?
✨ '일 잘하는' API의 7+1 원칙
제가 수많은 API를 써보고 또 만들어보면서 '아, 이건 정말 동료에 대한 배려가 넘친다!' 혹은 '이건 정말 이기적이다!' 싶었던 경험을 녹여낸 8가지 원칙입니다.
1️⃣ 원칙 1: 주소는 '자원(명사)', 행동은 '수단(동사)'으로!
API 주소(URI)에는 '무엇을'에 해당하는 자원(명사)만 명시하고, '어떻게 할지'는 HTTP 메서드(동사)가 담당하게 해야 합니다. 이게 REST의 가장 큰 철학이에요.
❌ 나쁜 예시: 주소에 행동이 포함됨
GET /getUsers, POST /createNewUser, POST /updateUser/123
✅ 좋은 예시: 주소는 자원만, 행동은 메서드가!
GET /users (사용자 목록 조회)
POST /users (새로운 사용자 생성)
PUT /users/123 (123번 사용자 정보 수정)
DELETE /users/123 (123번 사용자 삭제)
주소는 `/users`로 간결하게 유지하고, 행동의 의미는 동사(GET, POST, PUT, DELETE)에 명확히 위임하는 것, 이게 핵심입니다.
2️⃣ 원칙 2: 이름은 모두의 약속대로 (복수형 명사)
`user-list`, `productInfo`처럼 자기만의 규칙으로 이름을 지으면 다른 개발자는 혼란에 빠집니다. 이건 마치 도로에서 나 혼자 좌측통행을 하는 것과 같아요.
자원은 복수형 명사로 통일하는 것이 전 세계 개발자들의 불문율입니다. `/users`, `/products`, `/posts` 처럼요. 이 약속 하나만 지켜도 코드가 훨씬 프로페셔널해 보입니다.
3️⃣ 원칙 3: 버전 정보로 미래의 나를 구하세요 (v1, v2)
API는 살아있는 생물처럼 계속 변합니다. 만약 버전 정보 없이 API 구조를 바꿔버리면 어떻게 될까요? (`name` 필드를 `fullName`으로 바꾸는 순간!) 기존 API를 사용하던 모든 앱과 서비스는 그 즉시 멈춰버리는 대재앙이 발생합니다.
`/api/v1/users`, `/api/v2/users` 처럼 주소에 버전을 명시하는 건 미래에 발생할 재앙을 막는 가장 간단하고 확실한 보험입니다.
4️⃣ 원칙 4: 상태 코드로 명확하게 대화하기
서버는 감정이 없어요. 그래서 약속된 '상태 코드'로 명확하게 응답해야 합니다. "음... 잘 안됐는데 이유는 나도 잘..." 같은 애매한 응답은 최악이죠.
✅ 2xx (성공): 200 OK (요청 성공), 201 Created (생성 성공)
✅ 4xx (클라이언트 오류): 400 Bad Request (요청 잘못됨), 401 Unauthorized (인증 필요), 404 Not Found (자원 없음)
✅ 5xx (서버 오류): 500 Internal Server Error (우리 서버에 문제 생김!)
5️⃣ 원칙 5: 일관된 데이터 구조는 신뢰의 상징
A API는 성공 시 `{ "name": "..." }`, B API는 `{ "result": { "name": "..." } }` 처럼 제각각 응답을 주면, 사용하는 개발자는 매번 데이터 구조를 뜯어봐야 하는 스트레스를 받습니다. 동료의 '인지 부하'를 줄여주는 배려가 필요해요.
`{ "success": true, "data": [...], "error": null }` 과 같이 모든 응답을 일관된 구조로 감싸서 보내주는 것이 좋습니다.
6️⃣ 원칙 6: 필요한 만큼만 주는 센스 (필터링, 페이징, 정렬)
100만 개의 상품 데이터를 달라는 요청에 정말 100만 개를 다 던져주면 서버와 클라이언트 모두 다운될 겁니다. `?page=2&limit=10` (2페이지, 10개씩) 처럼 페이징 기능, `?status=active` 같은 필터링, `?sort=createdAt_desc` 같은 정렬 기능은 잘 만든 API의 필수 교양입니다.
7️⃣ 원칙 7: 보안은 선택이 아닌 의무!
HTTPS를 사용해 통신을 암호화하는 것은 기본이고, '당신은 누구인가요?(인증, Authentication)'와 '당신이 이 정보를 볼 자격이 있나요?(인가, Authorization)'를 명확히 구분하고 관리해야 합니다. 소중한 고객 정보를 아무나 볼 수 있게 내버려 둘 순 없잖아요?
🎁 보너스 원칙: 스스로 길을 안내하는 API 만들기 (HATEOAS)
조금 어려운 개념이지만, '최고의 API'를 꿈꾼다면 알아두세요. 응답 데이터에 관련된 다음 행동을 할 수 있는 '링크'를 함께 보내주는 겁니다.
예를 들어 123번 사용자의 정보를 요청하면, 응답에 사용자 정보뿐만 아니라 "이 사용자의 게시글 목록 보기: `/users/123/posts`", "이 사용자 정보 수정하기: `/users/123` (PUT)" 같은 링크를 포함해주는 거죠. API가 스스로 다음 할 일을 안내해주는 친절한 가이드가 되는 셈입니다.
제가 경험한 바로는, 이 원칙들만 잘 지켜도 팀 전체의
• 개발 속도: 불필요한 질문과 추측이 사라져 최소 30% 향상
• 버그 발생률: 예측 가능한 입출력 덕분에 절반 이하로 감소
• 협업 만족도: 서로에 대한 신뢰가 쌓여 200% 증가!
🎯 50대 개발자가 전하는 마지막 조언
결국 좋은 API 설계는 화려한 코딩 기술 이전에 '소통'과 '배려'의 문제라고 생각합니다.
이 API를 사용할 미래의 동료가 얼마나 편할까? 1년 뒤의 내가 이 코드를 보고도 "아하!"하며 바로 이해할 수 있을까? 이 질문을 항상 마음에 품고 설계하는 습관이야말로 최고의 개발자를 만드는 길입니다.
좋은 API는 그 자체로 최고의 '문서'이자, 팀의 '소통 규약'입니다.
누가 봐도 이해하기 쉽고, 예측 가능하며, 안전하고, 친절해야 합니다.
오늘 말씀드린 원칙들은 단순한 기술 규칙이 아니라, 성공적인 협업을 위한 '약속'이자 동료에 대한 '예의'입니다.
처음에는 이런 규칙들이 귀찮고 거추장스럽게 느껴질 수 있습니다. 하지만 딱 한 번만 제대로 된 '프랜차이즈 메뉴판'을 만들어보면, 그 메뉴판이 얼마나 많은 사람들을 편하게 해주는지, 그리고 그 편안함이 결국 나 자신에게 얼마나 큰 선물로 돌아오는지 분명히 깨닫게 되실 겁니다.
#RESTAPI, #API설계, #RESTfulAPI, #웹개발, #백엔드개발자, #초보개발자, #50대개발자, #개발팁, #코딩공부, #API가이드, #개발자, #프로그래밍, #IT정보, #협업, #서버개발, #개발문화