설명
POST는 리소스 생성이나 작업 요청 등 여러 용도로 사용됩니다. 성공 응답이 문서에 없으면 호출자가 생성 완료와 작업 접수 같은 결과를 구분하기 어렵습니다.
잠재적 영향
클라이언트가 아직 처리 중인 요청을 완료된 것으로 보거나 생성 결과를 잘못 처리할 수 있습니다.
해결 방법
새 리소스 생성은 201, 처리가 끝나지 않은 요청의 접수는 202 등 실제 결과를 나타내는 상태 코드를 문서화하세요. 202만으로 최종 성공이 보장되지는 않습니다. 응답 데이터나 후속 상태 확인 방법도 필요한 범위에서 설명하세요.
예시
다음 OpenAPI 3.0 발췌 예시는 새 항목 생성에 성공한 경우의 201을 추가합니다.
변경 전
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"post": {
"operationId": "createItem",
"summary": "Create item",
"responses": {
"default": {
"description": "Error"
}
}
}
}
}
}
변경 후
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"post": {
"operationId": "createItem",
"summary": "Create item",
"responses": {
"201": {
"description": "Item created successfully"
},
"default": {
"description": "Error"
}
}
}
}
}
}