onboardiq / rails-sunset

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

Rails Sunset

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.

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 2024 23:59:59 GMT

This can be combined with a Link: <http://foo.com/something> 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.

Usage

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 DateTime.new(2024, 1, 1), link: 'http://example.com/blog/get-them-foos-outta-here'

  # Deprecate only update and destroy but dont explain why
  sunset DateTime.new(2024, 1, 1), only: [:update, :destroy]

  # Deprecate just the one method with this shortcut
  sunset_method :create, DateTime.new(2024, 1, 1)

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

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

SUNSET_MILESTONES = {
  remove_legacy_endpoint: DateTime.new(2024, 2, 1),
  v2_needs_to_go: DateTime.new(2024, 4, 1),
}

# app/controllers/foo_controller.rb

sunset SUNSET_MILESTONES[:remove_legacy_endpoint], link: 'http://example.com/blog/get-them-foos-outta-here'

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

Requirements

• Ruby: v2.7.5
• Rails: v6.0 - v6.1

Note: We have dropped support for all rails versions prior to 6 to simplify this forking of this repository. If you need to support rails prior to version 6.0 we recommend using the original repository (https://github.com/wework/rails-sunset)

Testing

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

bundle exec appraisal rspec

Contributing

Bug reports and pull requests are welcome on GitHub at onboardidq/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.