In Rails, creating a controller that returns an HTML view is standard. But did you know that it is possible to return HTML, CSV, JSON, PDF, XML, and many other formats using the respond_to method in the same endpoint ?
That’s what we’ll explore today!
Table of Contents
What exactly is respond_to?
You can deal with a LOT of formats in the same endpoint
You can set default actions
You can set up customised Mime Types
You can mix variants and formats easily !
Conclusion
What exactly is respond_to?
To answer this question, let’s look at a concrete example of using respond_to.
Let’s start with this controller, ArticlesController, which has only one method: show.
def show
@article = Article.find(params[:id])
end
end
Thanks to Rails’ convention, we all know that the show method will return an HTML view. This HTML view is templated via the file app/views/articles/show.html.erb. All these rules are implicit because the default format is HTML.
But imagine that tomorrow you want to be able to return JSON instead of HTML, without changing your logic.
You would use respond_to!
def show
@article = Article.find(params[:id])
respond_to do |format|
format.html # will render show.html.erb
format.json { render json: @article }
end
end
end
From now on, you can pass a particular argument to your route: the format.
Let’s see how how it works using the routes helpers :
> app.article_path(1) # by default, format is HTML
=> “article/1”
> app.article_path(1, format: :json)
=> “article/1.json”
So, simply by adding the extension .json at the end of your route, it will call for JSON format !
Now that we have the basics, let’s look at some advanced use cases for respond_to.
You can deal with a LOT of formats in the same endpoint
As seen earlier, you can return JSON and HTML in the same method. But in fact, there are many other possible formats!
def show
@article = Article.find(params[:id])
respond_to do |format|
format.html # show.html.erb
format.json { render json: @article } # will automatically use #to_json
format.xml { render xml: @article.attributes } # will use #to_xml
format.csv { render csv: @article.attributes.to_a.to_csv }
format.pdf { render pdf: @article.generate_pdf } # let’s assume that generate_pdf returns a pdf file
end
end
end
With this syntax, you can handle many formats. I have listed here those I have already used in production projects, but there are many others. As many as your application supports MimeTypes.
You can set default actions
Suppose you want to define a default action when the format is not supported. There is the use of format.any that can save you!
def show
@article = Article.find(params[:id])
respond_to do |format|
format.html # show.html.erb
format.any { head :not_acceptable }
end
end
end
You can also specify in the any argument the formats you want to consider in your default action:
def show
@article = Article.find(params[:id])
respond_to do |format|
format.html # show.html.erb
format.any(:json, :xml, :csv) { head :not_acceptable }
end
end
end
It is important to note that if your route is called with an unsupported format, respond_to will raise an ActionController::UnknownFormat error.
You can set up customised Mime Types
Have you set up your own Mime Type? respond_to can still help you!
Mime::Type.register “application/custom_mime_type”, :custom
class ArticlesController < ApplicationController
def show
@article = Article.find(params[:id])
respond_to do |format|
format.custom { render plain: ‘Hello World!’ }
end
end
end
What is good to note here is that the HTTP response will always have the correct content-type header. In our case, the content-type will be application/custom_mime_type!
You can mix variants and formats easily !
Variants are a very powerful feature in Rails. Suppose you want to do a very simple A/B test:
def show
@article = Article.find(params[:id])
request.variant = [:a, :b].sample # always variant a or b
respond_to do |format|
format.html do |variant|
variant.a { @ author = nil } # show.html+a.erb
variant.b { @ author = @article.author } # show.html+b.erb
variant.none { head :no_content } # but you can still catch if there is no variant
end
end
end
end
Here we will only return HTML. Depending on the variant declared in request.variant, we can, for example, assign a value to @author.
We always have access to variant.none to be able to perform processing when no variant has been assigned to the request.
Conclusion
The respond_to method is a powerful tool, allowing you to respond to HTTP requests in various formats such as HTML, JSON, XML, CSV, and PDF. We have seen how respond_to can improve the flexibility of Rails applications by handling multiple formats in the same endpoint and setting default actions for unsupported formats.
I hope this article has made you appreciate the respond_to method. Don’t hesitate to subscribe so you don’t miss my next breakdown of Ruby and Rails.