REST API 에서의 HTTP 응답 코드 (HTTP 201 Created)

 

막연하게 알고, 대충 사용하던 HTTP 응답 코드를 정리할 시간.. 드디어..

한 번에 하려고 했는데 POST 하나 정리도 꽤나 걸려서 나눠서 정리해야겠다. 사실 아직 POST 말고는 궁금한 점이 없음.

 

< REST API에서의 HTTP 응답 코드 >

• 조회(GET) => 200 OK
• 생성(POST) => 201 Created
• 수정(PUT, PATCH) => 200 OK / 204 No Content
• 삭제(DELETE) => 204 No Content

 

---

🔶 생성(POST)

POST 요청 시 201 Created 응답을 보낸다.
이 때, Location 헤더에 생성된 리소스의 URI를 포함하는 것을 권장한다.

 

HTTP 201 Created

• 요청이 성공적으로 처리되었으며, 새로운 리소스가 생성되었음을 나타낸다.

 

URI를 생성하여 보내는 코드

    @PostMapping()
    public ResponseEntity<CommonResponse<MenuResponseDto>> createMenu(
        @RequestBody @Validated CreateMenuRequestDto requestDto) {
        MenuResponseDto responseDto = menuService.createMenu(requestDto);
        // URI 생성
        URI location = ServletUriComponentsBuilder.fromCurrentContextPath()
            .path("/api/menus/" + responseDto.getRmId().toString())
            .build()
            .toUri();
        // Location에 담아서 보내기
        return ResponseEntity.created(location)
            .body(new CommonResponse<>(SuccessCode.MENU_CREATE, responseDto));
    }

 

< HTTP 201 Created 응답에 URI를 포함하는 이유 >

1. HTTP 201 Created 응답 표준에 따르면 Location 헤더에 생성된 리소스의 URL을 포함하는 것이 규칙이다.
2. 클라이언트가 생성된 리소스를 쉽게 조회하도록 한다.

 

 1. HTTP 201 Created 응답 표준                            

HTTP 201에 대해서 단순하게 Location 헤더에 생성된 리소스 URI를 포함해서 보내자! 로 끝나면 좋겠다.
근데 왜 포함해서 보내야하는지 궁금함.. 이유 찾다가 머리만 더 복잡해지긴 했다.
영어로 읽어도, 한국어로 읽어도 이해가 안가서 AI의 힘을 빌렸다.

📌 쉽게 번역하면:
요청을 통해 새로 만들어진 주요 리소스(데이터)는 응답의 Location 헤더 필드에 있는 주소(URL) 로 식별됩니다.
만약 Location 헤더 필드가 포함되지 않았다면, 요청을 보낸 원래의 주소(URI) 가 새 리소스를 식별하는 역할을 합니다.

 

Location 헤더 필드에 주소가 있으면 그걸 자원의 주소로 인식하는 건 알겠다.
그런데, 포함되어 있지 않으면 원래 주소를 자원의 주소로 인식하는 걸까? 반드시 인식을 해야하는건가?

⚠️ 1. 왜 새로 생성된 리소스의 주소를 보내야 하는가?

=> RESTful API의 기본 원칙
REST API에서는 리소스가 특정한 URL로 식별되어야 한다.
즉, 데이터가 어디에 있는지(URL)가 명확해야 한다.

 

⚠️ 2. 왜 Location 헤더가 없을 때 요청한 URL이 새 데이터의 주소가 되는 걸까?

=> Location 헤더가 없는 경우, 기존 리소스가 업데이트되거나 개별 URL이 필요하지 않은 경우일 것이다.
(예. 프로필 사진을 업로드한다면 새로운 개별 리소스가 생성되는 것이 아니라 기존 프로필에 데이터가 변경되는 것이므로 기존 요청과 같아 새로운 주소가 필요하지 않다.

요청 : POST /api/users/123/profile-picture
조회 : GET /api/users/123/profile-picture
이런 개념인 듯하다. 요청 메서드가 다를 뿐 리소스 요청 주소는 같다?

⚠️ 3. 꼭 그 주소를 클라이언트가 가지고 있어야 하는건가?

이 부분은 아직도 이해하지 못하겠다. 클라이언트가 그 주소를 가지고 있는 게 아니라 필요할 때마다 api를 요청하는 것 아니었나..?

아무튼
모든 경우에 주소를 클라이언트가 가지고 있어야 하는 것은 아니고, 새로운 리소스에 직접 조회할 필요가 없다면 보낼 필요가 없다.

지피티가 예시를 들어줬다.

1.
클라이언트가 새로운 데이터를 생성

1-1.
그 데이터를 다시 조회하거나 수정하려면 클라이언트는 모든 리뷰를 가지고 와서 그 응답에서 방금 생성한 리뷰를 찾아야 한다. (그렇겠구만.. 새로 생성된 데이터의 id를 모르니까..?)

1-2. 
서버가 새로운 데이터의 URI를 포함하여 주면 그 URI로 바로 접근 가능!!

 

 2. 클라이언트가 생성된 리소스를 쉽게 조회      

생성되는 URI를 보면 왜 클라이언트가 쉽게 조회할 수 있는지 알 수 있다.
위에 코드로 생성된 URI의 예시는 아래와 같다.

GET http://localhost:8080/api/menus/123e4567-e89b-12d3-a456-426614174000

방금 생성된 리소스를 조회하는 URI가 클라이언트한테 완성된 상태로 전달되었기 때문에
그대로 요청해서 방금 생성된 리소스를 확인할 수 있다.
생성된 리소스의 id를 별도로 파싱하는 번거로움을 줄일 수 있는 것이다.

 

---

 

참고

https://www.rfc-editor.org/rfc/rfc9110#status.201