시작하며
개발자가 된 초기에 API를 호출할 때마다 "왜 에러가 나는 거지?"라며 머리를 쥐어뜯었던 기억이 있다. 특히 어려웠던 것은 파라미터를 어디에 써야 할지 모르겠다는 것이었다. URL에 써야 하는지, 요청 본문에 넣어야 하는지, 아니면 다른 곳인지...
당시에는 일단 모든 것을 URL에 붙여서 전송했다. 결과는 당연히 에러의 연속이었다. 선배에게 "기본기가 부족하네"라는 말을 듣고 나서야 Query, Path, Body의 차이를 제대로 배웠다.
그때의 아쉬움이 있었기에 지금 이 글을 쓰고 있다.
왜 파라미터 종류를 이해해야 할까?
API는 사람 간의 대화와 같다. 상대방에게 무언가를 전달할 때, 어떤 어조로, 어떤 방식으로 전달하느냐에 따라 상대방의 이해도가 달라진다.
- Query 파라미터: "이런 조건으로 검색해줘"
- Path 파라미터: "이 특정 리소스를 원해"
- Body 파라미터: "이 데이터를 처리해줘"
혼용하면 서버는 "무슨 말인지 모르겠다"며 당황하게 된다.
【실전편】3가지 파라미터 완전 분석
Query 파라미터: 검색·필터링의 왕
URL의 ? 이후에 작성하는 방식이다.
GET /users?role=admin&page=2&limit=10
사용 상황:
- 페이지네이션 (page, limit)
- 검색 조건 (keyword, category)
- 정렬 지정 (sort, order)
장점: URL만 봐도 무엇을 하는지 알 수 있음
단점: 너무 길면 URL이 지저분해짐
Path 파라미터: "이 사람"을 지정할 때의 필살기
URL의 일부로 포함되는 방식이다.
DELETE https://api.example.com/posts/:postId/comments/:commentId
URL 주소창에 위 URL을 입력하면 아래에 Path Variables 테이블이 자동으로 표시된다. 거기서 다음과 같이 설정:
postId=456commentId=789
사용 상황:
- 특정 사용자 정보 조회
- 특정 게시글 삭제
- 리소스의 고유 식별
주의점: 잘못 입력하면 404 에러 직행
Body 파라미터: 대용량 데이터의 운반책
요청 본문에 JSON이나 XML로 전송한다.
POST /api/users
{
"name": "김철수",
"email": "kim@example.com",
"department": "개발팀",
"skills": ["JavaScript", "Python", "Go"]
}
사용 상황:
- 사용자 등록·수정
- 파일 업로드
- 복잡한 데이터 구조 전송
실제 개발 현장에서 자주 하는 실수 패턴
흔히 하는 실패 사례
# 잘못된 예: Body 데이터를 모두 Query에 넣기
GET /api/users?name=김철수&email=kim@example.com&department=개발팀&skills=JavaScript,Python,Go
# 잘못된 예: Path 파라미터로 필터링 시도
GET /api/users/admin/page2/limit10올바른 구분법
# 정답: 적재적소
GET /api/users?role=admin&page=2 # 검색 조건은 Query
GET /api/users/123 # 특정 리소스는 Path
POST /api/users # 생성 데이터는 Body개발 효율을 극적으로 높이는 도구 선택
Postman vs Apidog: 현장에서의 활용법
Postman의 경우:
- Params 탭 → Query 파라미터 & Path 파라미터
- Body 탭 → Body 파라미터
Apidog의 경우:
- Params 탭 → Query 파라미터 & Path 파라미터
- Body 탭 → Body 파라미터
둘 다 기본적인 구조는 같지만, Apidog이 초보자에게 더 직관적인 UI 설계를 제공한다는 인상이다.
특히 마음에 드는 것은 자동 문서 생성 기능이다. API 명세서를 수동으로 만드는 수고를 덜 수 있고, 팀 개발에서 정말 유용하다. 파라미터 설정 실수도 줄어든 것 같다.
파라미터 선택의 황금 법칙
| 목적 | 사용할 파라미터 | 이유 |
|---|---|---|
| 검색·필터 | Query | URL로 조건 확인 가능 |
| 특정 리소스 지정 | Path | RESTful한 설계 |
| 데이터 생성·수정 | Body | 대용량·구조화 데이터 대응 |
헷갈릴 때의 판단 기준:
1. "검색 조건"이라면 → Query
2. "어떤 리소스"라면 → Path
3. "전송 데이터"라면 → Body
마무리
초보 시절처럼 파라미터 구분으로 고민할 필요는 이제 없다. Query, Path, Body의 특성을 이해하면 API와의 소통이 원활해진다.
특히 최근에는 Apidog 같은 직관적인 도구들도 등장하고 있다. 기술의 발전으로 예전만큼 "어디에 써야 할지 모르겠다"는 고민은 줄어들었다.
하지만 기초 이해는 반드시 필요하다. 도구에만 의존하지 말고, 왜 그곳에 파라미터를 두는지 그 이유를 이해해야만 진정한 의미에서 API를 다룰 수 있게 된다.
이 글이 도움이 되었다면 꼭 공유해주세요! 같은 고민을 하는 동료들이 있을지도 모릅니다. 또한 여러분의 경험담이나 추천 도구가 있다면 댓글로 알려주세요.
