Mark an endpoint as deprecated so everyone knows its going away!
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
gemfiles
lib
spec
.gitignore
.travis.yml
Appraisals
CHANGELOG.md
CODE_OF_CONDUCT.md
Gemfile
LICENSE
README.md
Rakefile
rails-sunset.gemspec

README.md

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

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

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

  # Use a lambda instead of a string to inject params
  sunset_method :destroy, DateTime.new(2019, 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 = {
  drain_the_swamp: DateTime.new(2018, 2, 1),
  v2_needs_to_go: DateTime.new(2018, 4, 1),
}
# app/controllers/foo_controller.rb

sunset SUNSET_MILESTONES[:drain_the_swamp], 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.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.

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 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.