Building a Screenshot Service with Ruby on Rails and SnapAPI

Ruby on Rails is a full-stack web framework that powers thousands of production applications, from early-stage startups to large-scale platforms. Its convention-over-configuration philosophy and rich ecosystem of gems make adding new capabilities to an existing Rails application straightforward. In this tutorial, you will add screenshot and PDF generation to a Rails application using SnapAPI, implementing a controller action that validates URLs, calls SnapAPI, and returns binary responses with appropriate caching headers.

Adding a Screenshot Controller to Rails

Rails controllers handle HTTP requests and return responses. Generate a new controller with rails generate controller Screenshots show. This creates a controller at app/controllers/screenshots_controller.rb and a route in config/routes.rb. In the show action, extract the target URL from params[:url], validate it, call SnapAPI using Ruby's Net::HTTP or the Faraday gem, and send the binary response using Rails' send_data method with the appropriate MIME type.

URL Validation in Rails

Use Ruby's built-in URI.parse combined with explicit scheme checking to validate that the target URL is a valid HTTP or HTTPS URL before making any external requests. Wrap the validation in a rescue block that catches URI::InvalidURIError and returns a 400 response with a JSON error body using Rails' render json: helper. Add an explicit check that the parsed URI scheme is either http or https, rejecting file, data, javascript, and ftp schemes that URI.parse accepts but should not be passed to SnapAPI. This two-layer validation provides defense against server-side request forgery without requiring any additional gems.

Storing the SnapAPI Key in Rails Credentials

Rails credentials provide an encrypted storage mechanism for API keys and other secrets. Run rails credentials:edit to open the encrypted credentials file and add your SnapAPI key under a snapapi_key entry. Access it in your controller with Rails.application.credentials.snapapi_key. The credentials file is encrypted with your Rails master key, which you store separately from the credentials file -- in an environment variable in production and in a local file excluded from version control in development. This approach ensures your SnapAPI key is never committed to your Git repository in plaintext.

Calling SnapAPI with Faraday

Faraday is Ruby's most popular HTTP client gem, offering a middleware-based architecture and consistent interface across connection adapters. Add gem 'faraday' to your Gemfile and run bundle install. In your controller, create a Faraday connection to the SnapAPI base URL with a 30-second timeout and a connection adapter appropriate for your Rails server -- the default net_http adapter works correctly in most cases. Make a GET request to the SnapAPI screenshot endpoint with your key in the Authorization header and the target URL as a query parameter. Check the response status before calling send_data with the response body.

Background Jobs with Sidekiq

For Rails applications where screenshot generation is triggered by user actions but results are consumed asynchronously, Sidekiq provides reliable background job processing. Define an ApplicationJob that calls SnapAPI, stores the result in Active Storage, and triggers a notification to the requesting user when the screenshot is ready. Your controller action enqueues the Sidekiq job and returns a 202 response with the job ID immediately. The user's frontend polls a status endpoint until the screenshot is available, then fetches it from Active Storage. This architecture keeps your Rails controllers responsive even when SnapAPI calls take multiple seconds for complex page rendering.

Caching with Rails.cache

Rails provides a unified caching interface through Rails.cache that works with Redis, Memcached, and file-based backends depending on your environment configuration. Cache SnapAPI responses by URL hash to reduce API credit consumption and improve response times for repeated screenshot requests. In your controller, compute a cache key by hashing the target URL and screenshot parameters with Digest::MD5. Call Rails.cache.fetch(cache_key, expires_in: 1.hour) with a block that calls SnapAPI on a cache miss. The cached binary content is returned immediately on subsequent requests for the same URL within the cache window, with no SnapAPI call required.