Description
HEAD retrieves resource metadata without a response body. Without a defined success response, callers and automated tools may be unable to identify a normal result.
Potential impact
Clients that check resource existence or availability may treat a normal response as a failure.
Remediation
Define the actual success codes, such as 200, and their meaning in responses. Describe relevant response headers, but do not define a body for a HEAD response.
Examples
This OpenAPI 3.0 excerpt adds a 200 success response alongside the default response described as an error.
Before
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"head": {
"operationId": "headItem",
"summary": "Head item",
"responses": {
"default": {
"description": "Error"
}
}
}
}
}
}
After
json
{
"openapi": "3.0.0",
"paths": {
"/item": {
"head": {
"operationId": "headItem",
"summary": "Head item",
"responses": {
"200": {
"description": "Success"
},
"default": {
"description": "Error"
}
}
}
}
}
}