REST API 자주 묻는 질문: 설계·구현·테스트에서 바로 쓰는 판단 기준

REST API 자주 묻는 질문을 찾는 독자는 핵심 개념은 이해해도 설계, 구현, 테스트 단계에서 선택 기준이 흔들리는 경우가 많습니다. 이 글은 강력하고 유연한 웹 서비스를 만들 때 자주 부딪히는 질문만 골라 짧게 답하고, 바로 다음에 확인할 실무 기준을 붙인 FAQ입니다.

핵심 질문

REST API와 RESTful API는 같은 말인가

짧은 답: 비슷하게 쓰이지만 완전히 같은 뜻으로 단정할 필요는 없습니다. REST API는 REST 원칙을 참고한 HTTP API를 넓게 가리키는 표현이고, RESTful API는 그중 자원 중심 설계와 제약을 더 일관되게 지키는 경우에 가깝습니다.

추가 확인: URI가 동사보다 자원을 드러내는지, 메서드 의미가 URI 안의 동작 이름을 대신하고 있는지, 상태 코드와 응답 구조가 문서와 구현에서 같은 형태를 유지하는지를 보면 과장 없이 구분할 수 있습니다.

자원 중심 설계는 어디까지 지켜야 하나

짧은 답: 모든 것을 완벽한 명사형으로 만들기보다, 클라이언트가 무엇을 조회하고 생성하고 수정하는지 분명하게 드러나는 수준이면 충분합니다.

추가 확인: /createUser보다 /users, /users/{id}처럼 자원을 기준으로 두고, 정말 자원으로 설명하기 어려운 경우에만 예외를 좁게 허용하는 편이 유지보수에 유리합니다.

간단 답변

POST, PUT, PATCH는 어떻게 나누나

짧은 답: 새 자원 생성이나 서버가 식별자를 정하는 작업은 보통 POST, 전체 교체 성격은 PUT, 일부 필드 변경은 PATCH가 자연스럽습니다.

추가 확인: 같은 요청을 여러 번 보내도 같은 결과로 수렴해야 하는지 먼저 보세요. 결과가 계속 누적되면 POST 쪽에 가깝고, 같은 상태로 맞춰지면 PUT이나 PATCH 후보입니다. PATCH를 쓸 때는 누락 필드가 유지인지 삭제인지 규칙을 문서에 명확히 적어야 합니다.

200, 201, 204는 언제 쓰나

짧은 답: 성공했고 본문을 돌려주면 200, 새 자원이 생성되면 201, 성공했지만 본문이 없으면 204가 보통 맞습니다.

추가 확인: 새 식별자가 생기는 생성 요청은 201을 우선 검토하고, 삭제 성공이나 본문 없는 상태 변경은 204가 깔끔합니다. 반대로 수정 뒤 최신 자원 표현을 바로 돌려주면 200이 더 읽기 쉽습니다.

400, 404, 409, 422는 어떻게 구분하나

짧은 답: 요청 형식 자체가 잘못됐으면 400, 자원이 없으면 404, 현재 상태와 충돌하면 409, 형식은 맞지만 유효성 검사나 업무 규칙을 통과하지 못하면 422로 나누면 실무에서 설명이 쉬워집니다.

추가 확인: 예를 들어 JSON 구조가 깨졌다면 400, 존재하지 않는 주문 번호 조회는 404, 이미 처리 완료된 주문을 다시 취소하려는 경우는 409, 이메일 형식 오류나 길이 제한 위반은 422처럼 정리할 수 있습니다. 중요한 점은 팀 문서와 구현이 같은 기준을 반복해서 써야 한다는 것입니다.

페이징, 정렬, 필터 파라미터는 무엇이 중요하나

짧은 답: 이름보다 일관성이 더 중요합니다.

추가 확인: page, size, sort, filter처럼 기본 형태를 먼저 고정하고, 컬렉션 엔드포인트마다 같은 규칙을 유지하세요. 정렬 방향 표기 방식과 필터의 정확 일치, 범위 검색 표현을 초기에 정해 두면 설계와 구현, 테스트가 훨씬 단순해집니다.

인증은 API Key, JWT, OAuth 중 무엇이 정답인가

짧은 답: 정답은 하나가 아니라 목적이 다릅니다.

추가 확인: 서버 간 단순 식별과 호출 제어가 중심이면 API Key가 가볍고, 사용자 인증 상태를 포함한 자체 서비스 토큰 운용이 필요하면 JWT가 자주 쓰입니다. 제3자 로그인이나 권한 위임이 핵심이면 OAuth 계열을 검토하는 편이 자연스럽습니다. 어떤 방식을 택하든 만료, 재발급, 권한 범위, 로그 노출 금지 기준을 함께 정해야 실제 운영에서 덜 흔들립니다.

버전 관리는 처음부터 해야 하나

짧은 답: 버전 번호를 바로 노출할지와 별개로, 변경 호환성 기준은 초기에 정리해 두는 편이 좋습니다.

추가 확인: 필드 추가는 허용하는지, 필드 이름 변경이나 삭제는 어떤 절차를 거치는지, 구버전 종료 공지는 어디에 남길지 정리해 두면 나중에 구현보다 커뮤니케이션 비용이 줄어듭니다.

• 에러 응답 형식은 통일해야 하나: 네. 코드, 메시지, 세부 필드 오류 위치 정도는 공통 구조를 유지하는 편이 클라이언트와 테스트 작성에 유리합니다.
• 문서화는 구현 뒤에 해도 되나: 가능하지만 권장되지는 않습니다. 설계 단계에서 초안을 잡아 두면 구현과 테스트가 같은 기준을 공유하기 쉽습니다.
• 검색 결과 예시를 그대로 믿어도 되나: 아니요. 블로그 문구, 샘플 코드, 외부 Q&A는 맥락이 빠진 경우가 많아 출처와 적용 범위를 분리해 읽어야 합니다.
• 실제 요청 예시는 꼭 필요한가: 네. URI, 헤더, 요청 본문, 응답 본문, 실패 예시가 같이 있어야 팀이 같은 API를 다르게 이해하는 일을 줄일 수 있습니다.

이런 문맥 분리 습관은 개발 문서 밖에서도 유용합니다. 예를 들어 지역 서비스 검색 결과의 후기 문구나 개인정보 요구 표현을 해석하는 기준이 궁금하다면 셔츠룸 확인 기준처럼 과장 표현과 실제 정보 단서를 구분하는 정보형 예시를 참고해 읽기 기준을 다듬어 볼 수 있습니다.

추가 확인

테스트는 무엇부터 포함해야 하나

짧은 답: 정상 흐름만 통과해도 충분하지 않습니다.

추가 확인: 최소한 정상 응답, 권한 오류, 유효성 검사 실패, 중복 요청 처리는 기본 세트로 넣으세요. 여기에 존재하지 않는 자원 조회, 동시 수정 충돌, 빈 결과 목록, 최대 길이와 최소 길이 같은 경계 조건을 더하면 설계와 구현의 어긋남이 빨리 드러납니다.

문서와 테스트를 한 묶음으로 봐야 하는 이유는 무엇인가

문서가 설계의 약속이라면 테스트는 그 약속이 실제 구현에서 지켜지는지 확인하는 장치입니다. 문서에는 422를 쓰겠다고 적어 두고 테스트는 400만 확인하면 팀 내부에서 API 해석이 갈라집니다. 그래서 엔드포인트 설명, 상태 코드, 에러 형식, 예시 요청과 응답, 테스트 케이스는 같이 유지되는 편이 좋습니다.

관련해서 문서 해석 중심의 흐름을 더 보고 싶다면 REST API 정보 활용 상황별 읽기 가이드와 REST API 설명 문구 검증 기준: 소개 문장과 실제 글이 맞는지 보는 법도 함께 참고할 수 있습니다.

마지막 점검은 어떻게 하나

1. 엔드포인트가 기능 이름보다 자원 중심으로 읽히는지 확인합니다.
2. HTTP 메서드와 상태 코드가 실제 동작과 일관되게 맞물리는지 봅니다.
3. 페이징, 정렬, 필터, 에러 응답 형식이 모든 관련 엔드포인트에서 같은 규칙을 유지하는지 확인합니다.
4. 인증과 버전 관리 기준이 문서에 먼저 적혀 있고 테스트에도 반영됐는지 점검합니다.
5. 정상 케이스뿐 아니라 실패 케이스와 경계 조건까지 테스트가 닿는지 확인합니다.

REST API는 규칙 이름을 많이 아는 것보다, 언제 어떤 기준을 적용할지 빠르게 판단하는 능력이 더 중요합니다. 짧은 답을 먼저 정리하고 그 뒤에 설계, 구현, 테스트의 확인 항목을 붙여 두면 팀이 같은 방향으로 강력하고 유연한 웹 서비스를 만들기 쉬워집니다.