Description
POST serves several purposes, including creating resources and submitting work. Without a documented success response, callers may be unable to distinguish resource creation from acceptance of a job.
Potential impact
Clients may treat pending work as completed or mishandle a resource-creation result.
Remediation
Document codes that reflect the actual result, such as 201 for creation or 202 for acceptance before processing finishes. A 202 response does not guarantee eventual success. Explain response data or subsequent status checks where needed.
Examples
This OpenAPI 3.0 excerpt adds 201 for successful creation of a new item.
Before
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"post": {
"operationId": "createItem",
"summary": "Create item",
"responses": {
"default": {
"description": "Error"
}
}
}
}
}
}
After
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"post": {
"operationId": "createItem",
"summary": "Create item",
"responses": {
"201": {
"description": "Item created successfully"
},
"default": {
"description": "Error"
}
}
}
}
}
}