Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Rails Sunset

Build Status Coverage Status MIT License

Rails Sunset lets you deprecate URLs (API or otherwise) in a Railsy way. Why? Because we all have those trash endpoints we'd love to delete, but we can't just delete them without turning that trash into a full-on garbage fire.

Take out the garbage

The Sunset header is an in-development HTTP response header that is aiming to standardize how URLs are marked for deprecation. tl:dr; it looks a bit like this:

Sunset: Sat, 31 Dec 2018 23:59:59 GMT

This can be combined with a Link: <> rel="sunset" which can be anything that might help a developer know what is going on. Maybe link to your API documentation for the new resource, the OpenAPI/JSON Schema definitions, or even a blog post explaining the change.


gem 'rails-sunset'

Using it in your controllers is as simple as calling the sunset class method:

class FooController
  # Deprecate all methods and point them to a blog post
  sunset, 1, 1), link: ''

  # Deprecate only update and destroy but dont explain why
  sunset, 1, 1), only: [:update, :destroy]

  # Deprecate just the one method with this shortcut
  sunset_method :create,, 1, 1)

  # Use a lambda instead of a string to inject params
  sunset_method :destroy,, 1, 1), link: -> { v3_company_url(params['id']) }

These deprecations are logged to the Rails.logger, and output with ActiveSupport::Deprecation. You can configure ActiveSupport::Deprecation to warn in a few different ways, or pass in any object that acts a bit like a Rack logger, Rails logger, or anything with a warn method that takes a string.

Handling Those Dates

Literring your controllers with all those dates certainly doesn't seem ideal, it's basically magic numbers.

One approach would be to make a config/initializer/deprecations.rb with some "milestones" like this:

# config/initializer/deprecations.rb

  drain_the_swamp:, 2, 1),
  v2_needs_to_go:, 4, 1),
# app/controllers/foo_controller.rb

sunset SUNSET_MILESTONES[:drain_the_swamp], link: ''

Call em what you want, but something like this should keep things on track.


  • Ruby: v2.2 - v2.4
  • Rails: v4.2 - v5.2

Note: Although we support Ruby v2.4 and Rails v4.2, they don't really like each other all that much. As such, expect failures on Travis for that combination.


To run tests and modify locally, you'll want to bundle install in this directory.

bundle exec appraisal rspec


Bug reports and pull requests are welcome on GitHub at wework/rails-sunset. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.


Mark an endpoint as deprecated so everyone knows its going away!




No packages published