CUD 에 따른 반환 값 및 상태 코드
글을 쓰게 된 이유
지하철 미션 때 CRUD에 따른 상태 코드 및 반환 값을 다시 한번 생각해 보자라는 리뷰를 받았었습니다.
평소에 저는 POST 요청 시 id를 반환하고, DELETE나 PATCH/PUT 연산 시에는 반환 값이 없었습니다. 물론 상태 코드도 명시하지 않았고요.
상태 코드 반환은 좋다고 생각하지만, POST, PATCH/PUT 때 값을 반환하는 것은 좋지 않다고 생각했습니다.
왜냐하면 "각각 생성, 수정에 대한 책임을 가지는 것이지 조회까지 해줘야 하나?"라는 생각으로요.
하지만 우테코에 온 만큼 이러한 세세한 부분도 제대로 공부하고자 실제 기업에서는 API 스펙을 어떻게 정의했는지,
RFC 문서에서는 어떻게 정의되어 있는지 HTTP 메서드마다 살펴보겠습니다.
POST
POST는 리소스를 저장하는 데 사용되는 HTTP Method입니다.
RFC 문서에서는 서버에 리소스가 새로 생기게 되면, 응답은 201 Created를 사용하고, 새 리소스를 참조하는 엔티티와 위치 헤더를 포함해야 한다고 합니다.
이때 위치 헤더는 redirect를 하는 데 사용된다고 합니다.
mozilla 문서를 보면 POST 가 성공적으로 수행됐다면 새로 생성된 항목은 요청의 URL 또는 Location 헤더 값에 URL을 포함한다고 합니다.
HTTP API 문서들을 보면 공통적으로 POST 요청에 대한 응답이 성공적으로 처리될 경우엔 상태 코드로는 201 Created를 사용하고, 헤더에 리소스가 저장된 위치를 반환한다고 합니다.
이제 기업들은 이러한 HTTP 스펙을 지키고 있는지 보도록 하겠습니다.
Twilio, Stripe, GitHub API docs를 보면 location header에 저장된 URL을 반환하진 않지만 저장된 리소스를 반환합니다.
(왼쪽부터 순서대로)
PUT
PUT은 리소스 수정 HTTP Method입니다.
Mozilla에서도 PUT이나 DELETE는 종종 200 OK 보다는 204 No Content 응답 코드를 내린다고 합니다.
204 No Content 의미는 요청 성공했지만 클라이언트가 현재 페이지에서 벗어날 필요가 없음을 나타낸다고 합니다.
If a new resource is created, the origin server MUST inform the user agent via the 201 (Created) response. If an existing resource is modified, either the 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request.
RFC 문서에서도 또한 PUT을 사용할 때, 새 리소스가 생성되면 201 Created, 기존 리소스가 수정된 경우 200 또는 204 응답 코드를 보내야 한다고 명시되어 있습니다.
이제 기업들은 어떻게 사용하는지 보도록 하겠습니다.
trillio는 Add or Update에서 PUT을 사용하거나 수정만 할 때도 사용합니다.
대부분 수정할 경우에 PATCH를 사용하지만 가끔 PUT도 사용합니다.
또한, 같은 HTTP Method인 PUT을 사용하지만 다른 상태 코드를 반환하기도 합니다.
stripe는 PUT 도 사용하지만 대부분 Update 관련 HTTP Method를 POST로 사용하는 것을 알 수 있습니다.
그때 수정된 값을 같이 반환해 줍니다.
GitHub을 보시면 아래 두 개는 모두 PUT 요청이지만 각각 상태 코드가 200, 204로 다른 것을 알 수 있습니다.
물론 200 일 때는 body로 수정된 값을 보내주지만, 204 때는 보내주지 않습니다.
DELETE
RFC 문서에서는 성공적인 응답에서는 200, 아직 실행되지 않은 경우 202, 응답에 엔티티가 포함되지 않는 경우 204를 반환합니다.
Mozilla에서도 앞서 말한 것처럼 종종 200 대신에 204를 사용하는 경우도 있다고 합니다.
stripe에서는 DELETE를 사용할 경우 대부분 200과 함께 삭제된 엔티티를 반환합니다.
twilio에서는 DELETE를 사용할 경우 API 마다 다르게 됩니다.
상태코드도 다르고, 반환 여부도 달라지게 됩니다.
GitHub을 보면 응답 코드가 204이면 body가 비어있고, 200이면 삭제된 값을 반환해 줍니다.
결론
회사마다 HTTP API 스펙이 다른 것을 알 수 있습니다.
즉, HTTP API는 스펙일 뿐 꼭 지켜야 하는 것은 아닙니다.
다만 범용적으로 사용되는 개념 안에서 다르게 사용하는 것이지, 예를 들어서 POST인데 4xx 응답 코드를 사용하지 않는 것처럼요.
stripe에서와 같이 수정에서 대부분 POST를 사용하듯, 이렇게 사용을 다르게 할 수 있습니다.
결국 API 설계를 할 때, 팀 간의 컨벤션처럼 백엔드 입장에서는 프론트와 맞춰가는 것으로 생각합니다.
앞서 말한 것처럼 그 개념 안에서 벗어나지 않고 설계를 한다면 맞다/틀리다의 개념이 없어집니다.
해당 API에서는 어떤 응답 코드가 잘 어울리는지, 어떤 상황에서는 어떤 응답 코드를 사용하는지,
API 연산에 따라서라도 HTTP Method를 달리할 수 있습니다.
그렇기 때문에 상황에 잘 맞게 사용하는 것이 중요한 것을 느낄 수 있었습니다.
그리고 개인적으로 GitHub API docs가 문서와 가장 가까운 형태를 띠는 것 같습니다.
만약 RESTful API에 대해 공부하려면 레퍼런스로 GitHub API docs 보는 것을 추천합니다.
REFERENCES