PUT은 새로 만들기일까 기존 내용을 바꾸기일까

PUT은 대상 자원을 만들거나 표현을 대체하는 요청입니다

PUT을 무조건 기존 항목의 일부 수정이라고 해석하면 누락한 값의 의미를 놓칠 수 있습니다. 대상 자원이 없으면 생성, 있으면 보낸 표현으로 대체하는 요청으로 정의됩니다. 어떤 필드가 필수인지와 생략·null을 어떻게 처리하는지는 해당 API 계약을 함께 읽어야 합니다. 근거: MDN PUT, 2026-11-04 확인.

근거: MDN PUT 요청 메서드 · 2026-11-04 확인

이름만 바꾸려는 프로필 예제

가상의 프로필이 {name: Mina, city: Seoul}이라고 합시다. 이름만 바꾸려고 {name: Jina}를 PUT으로 보냈을 때 city가 유지되는지 지워지는지는 임의로 추정하지 않습니다. 이 표기는 실제 전송 JSON이 아닌 필드 관계를 보여 주는 예입니다. 전체 표현을 요구하는 API라면 필요한 기존 필드와 새 값을 갖춰 보내야 하며, 일부 변경용 API가 별도로 있다면 그 문서를 사용합니다.

근거: MDN PUT 요청 메서드 · 2026-11-04 확인

요청을 만들기 전 세 가지를 적습니다

첫째, 대상 URI를 클라이언트가 지정하는지 확인합니다. 둘째, 전체 필드 목록과 서버가 관리하는 읽기 전용 값을 구분합니다. 셋째, 생략과 빈 문자열, null의 차이를 기록합니다. 오래전에 내려받은 전체 표현을 그대로 보내면 다른 사용자의 변경을 덮을 수 있으므로 동시 수정에 대한 버전 조건이나 갱신 정책도 확인합니다. 이 조건의 헤더 이름과 실패 응답은 서비스 문서에 맞춥니다.

근거: MDN PUT 요청 메서드 · 2026-11-04 확인

테스트는 보내기 전 상태와 저장 뒤 상태를 대조합니다

시험이 허가된 자원에 현재 상태를 저장하고 변경하려는 값과 유지되어야 할 값을 적습니다. PUT 한 번 뒤 응답 상태를 읽고 다시 조회해 그 두 목록이 모두 맞는지 확인합니다. 생성이라면 새 자원이 실제 조회되는지, 대체라면 예상 필드가 누락되지 않았는지 봅니다. 응답 성공만 있고 다시 조회한 표현이 다르다면 업무 요구를 충족한 성공으로 기록하지 않습니다.

반복해도 같은 상태라는 말은 응답 복제를 뜻하지 않습니다

같은 PUT의 의도한 최종 상태는 반복 횟수로 달라지지 않는 멱등성을 갖습니다. 하지만 첫 호출의 생성 응답과 이후 대체 응답은 다를 수 있고 로그·수정 시각도 관찰될 수 있습니다. 실제 서버가 이 의미를 따르는지는 구현 문제입니다. 테스트에서 같은 본문을 반복했을 때 항목 수가 늘어나는 등 차이가 나면 API 담당자에게 동작 계약을 확인합니다.

실패하면 누락 필드를 보태기 전에 원인을 구분합니다

본문 형식·필수 필드 오류라면 오류 설명과 계약을 대조하고, 접근 거부라면 권한을 확인합니다. 버전 충돌이면 최신 상태를 다시 읽고 사용자의 변경 의도를 보존해 새 요청을 준비합니다. 타임아웃 뒤에는 저장 결과를 먼저 조회합니다. 오류를 없애려고 문서에 없는 값을 임의로 채우거나 운영 자원을 반복 덮어쓰지 않습니다.

옆 문서로 이어가기