When to Use head vs render in Rails Controllers

In Ruby on Rails, controller actions usually return responses using render. However, in many cases—especially in APIs—you only need to return an HTTP status code without a response body. That’s exactly what head is for.

What Is head?

head is a method provided by Rails controllers (via ActionController::Metal) that allows you to send an HTTP response with:

• A status code
• Headers (if needed)
• No response body

This is particularly useful for API responses where the body is not needed.

What Is render?

render is the most common way to send a response in a Rails controller. Unlike head, it sends a full HTTP response including a body. You can use it to return:

• HTML (from a view template)
• JSON (for API responses)
• Plain text
• Partial templates

Common Use Cases for head

1. Successful Action with No Content

You want to confirm that an action succeeded but don’t need to return any data:

1
head :no_content # HTTP 204

2. Simple Status Confirmation

For example, when a resource is updated successfully:

1
head :ok # HTTP 200

3. Error Response Without Details

You want to return a failure status without including error messages in the response body:

1
head :unprocessable_entity # HTTP 422

4. RESTful API Design

Many REST APIs return only HTTP status codes for certain actions like PUT, PATCH, or DELETE, without any response body.

Comparing head and render

Using head and render in Rails API Responses

Here’s a controller action that uses both head and render appropriately:

1
2
3
4
5
6
7
def destroy
  if resource.destroy
    head :no_content  # HTTP 204
  else
    render json: { error: "Could not delete resource" }, status: :unprocessable_entity
  end
end

This pattern is common in APIs where you want lightweight, status-only responses for success and more detailed responses for errors.

• Use head when no response body is needed—just headers and a status code.
• Use render when you need to return content, such as JSON or HTML.
• head is especially helpful for building clean, efficient RESTful APIs.