HTTP POST

HTTP POST는 요청에 담긴 데이터를 대상 자원이 정한 방식으로 처리하도록 요구하는 HTTP 메서드입니다. 회원 가입, 게시물 등록, 계산 실행처럼 서버에 처리를 맡기는 데 사용합니다. 구체적인 결과는 요청 주소와 API 계약에 따라 달라지며, 같은 요청을 반복했을 때 효과가 한 번과 같다는 보장은 메서드 자체에 없습니다.

요청 본문과 처리 규칙

HTTP 의미론 표준 RFC 9110은 POST를 대상 자원의 고유한 의미에 따라 요청 내용을 처리하는 메서드로 정의합니다. 서버는 주소와 메서드에 맞는 처리 코드를 고르고 전달받은 값을 읽습니다. 게시판에 글을 추가하는 동작도 여기에 해당하지만, 기존 자료에 주석을 붙이거나 입력을 계산하는 용도로도 사용합니다. POST라는 이름만으로 데이터베이스의 새 행이 생긴다고 결정되지는 않습니다.

본문의 형식은 별도로 전달합니다. JSON 데이터를 보내는 API라면 서버가 그 형식으로 읽을 수 있도록 본문과 Content-Type을 맞춥니다. 주소가 정확해도 JSON이 잘못됐거나 필수 값이 빠지면 요청을 거부할 수 있습니다. HTTP 메서드는 처리의 큰 의미를 정하고, 어떤 필드가 필요한지와 어떤 값을 허용하는지는 해당 API의 문서가 정합니다.

MDN의 POST 설명은 HTML 폼에서 사용하는 application/x-www-form-urlencoded와 파일 전송에 쓰는 multipart/form-data 등을 소개합니다. 같은 POST 요청이어도 전송 형식이 다르면 서버의 해석 방법도 달라집니다. API 호출 코드를 살필 때는 본문 문자열만 읽기보다 실제 헤더와 본문이 한 쌍으로 맞는지 확인하면 오류 원인을 좁히기 쉽습니다.

GET과 PUT의 의미 차이

GET은 대상 자원의 표현을 가져오는 메서드입니다. POST는 서버가 입력에 맞는 처리를 수행하도록 요청합니다. 검색 조건을 본문으로 받는 API가 POST를 선택할 수도 있으므로, 화면에 조회 결과만 나타난다는 이유로 실제 요청을 GET이라고 판단하지 않습니다. 어떤 메서드를 쓸지는 개발자가 화면의 목적만 보고 바꾸는 값이 아니라 서버가 제공하는 인터페이스와 함께 정해집니다.

PUT은 지정한 대상 자원의 상태를 요청 내용으로 만들거나 대체한다는 의미를 가집니다. POST에서는 대상 자원이 입력을 어떻게 처리할지 정합니다. RFC 9110의 메서드 규칙은 PUT을 멱등 메서드로 분류하지만 POST에는 그 성질을 부여하지 않습니다. 멱등성은 동일한 요청을 반복한 의도된 효과가 한 번 보낸 효과와 같은지를 뜻하며, 매번 응답 본문이 똑같아야 한다는 뜻은 아닙니다.

POST가 HTTP의 안전한 메서드로 분류되지 않는다는 말도 용어상의 구별입니다. 여기서 안전성은 사용자가 서버 상태 변경을 요청하는 의미인지에 관한 성질입니다. 통신을 암호화하는 HTTPS나 사용자 권한 검사와는 판단 대상이 다릅니다. HTTPS로 보낸 POST라도 같은 주문을 두 번 만들 수 있고, 암호화된 연결에서도 권한이 없는 요청은 거부될 수 있습니다.

재시도와 성공 응답의 해석

주문 요청을 보낸 뒤 응답을 받기 전에 연결이 끊기면 서버에서 주문이 만들어졌는지 클라이언트가 알지 못할 수 있습니다. 이 상태에서 요청을 그대로 반복하면 중복 주문이 생길 가능성이 있습니다. API가 중복 방지 식별자나 처리 상태 조회를 제공한다면 그 계약에 따라 재시도를 구성합니다. 특정 서비스의 중복 방지 기능을 모든 POST 요청이 갖는 성질로 확대하지 않습니다.

응답의 상태 코드와 본문은 처리 결과를 읽는 단서입니다. 새 자원을 만들었다면 201 응답이 사용될 수 있고, 처리를 접수했지만 끝나지 않았다면 202 응답이 사용됩니다. 응답을 받았다는 사실과 사용자가 원하는 작업이 최종 완료됐다는 사실은 다릅니다. 오래 걸리는 작업은 반환된 작업 식별자로 진행 상태를 조회하는 별도 절차를 둘 수 있습니다.

실패를 조사할 때는 메서드, 대상 주소, 콘텐츠 형식, 상태 코드와 서버의 오류 설명을 함께 기록합니다. 자격 증명이나 개인정보는 진단 기록에서 제외합니다. AI 에이전트가 API를 호출하는 경우에도 POST 요청을 만들어 냈다는 사실만으로 실행 성공을 보고하지 않고, 서버 응답과 필요한 후속 조회에서 실제 결과가 확인됐는지 구별합니다.