Add Deprecation headers to collections alpha API (#39349)

app/controllers/api/base_controller.rb

@@ -100,4 +100,8 @@ class Api::BaseController < ApplicationController
   def respond_with_error(code)
     render json: { error: Rack::Utils::HTTP_STATUS_CODES[code] }, status: code
   end
+
+  def alpha_path?
+    request.path.starts_with?('/api/v1_alpha')
+  end
 end

app/controllers/api/v1/collection_items_controller.rb

@@ -2,6 +2,9 @@
 
 class Api::V1::CollectionItemsController < Api::BaseController
   include Authorization
+  include DeprecationConcern
+
+  deprecate_api '2026-06-10', if: :alpha_path?
 
   before_action -> { doorkeeper_authorize! :write, :'write:collections' }
 

app/controllers/api/v1/collections_controller.rb

@@ -2,6 +2,7 @@
 
 class Api::V1::CollectionsController < Api::BaseController
   include Authorization
+  include DeprecationConcern
 
   DEFAULT_COLLECTIONS_LIMIT = 40
   MAX_COLLECTIONS_LIMIT = 100
@@ -10,6 +11,8 @@ class Api::V1::CollectionsController < Api::BaseController
     render json: { error: ValidationErrorFormatter.new(e).as_json }, status: 422
   end
 
+  deprecate_api '2026-06-10', if: :alpha_path?
+
   before_action -> { authorize_if_got_token! :read, :'read:collections' }, only: [:index, :show]
   before_action -> { doorkeeper_authorize! :write, :'write:collections' }, only: [:create, :update, :destroy]
 

spec/requests/api/v1/collection_items_spec.rb

@@ -5,9 +5,9 @@ require 'rails_helper'
 RSpec.describe 'Api::V1Alpha::CollectionItems' do
   include_context 'with API authentication', oauth_scopes: 'read:collections write:collections'
 
-  describe 'POST /api/v1_alpha/collections/:collection_id/items' do
+  describe 'POST /api/v1/collections/:collection_id/items' do
     subject do
-      post "/api/v1_alpha/collections/#{collection.id}/items", headers: headers, params: params
+      post "/api/v1/collections/#{collection.id}/items", headers: headers, params: params
     end
 
     let(:collection) { Fabricate(:collection, account: user.account) }
@@ -28,6 +28,14 @@ RSpec.describe 'Api::V1Alpha::CollectionItems' do
           expect(response).to have_http_status(200)
           expect(response.parsed_body).to have_key('collection_item')
         end
+
+        it 'features a deprecation header when requested via the alpha route' do
+          subject
+          expect(response.headers['Deprecation']).to be_nil
+
+          post "/api/v1_alpha/collections/#{collection.id}/items", headers: headers, params: params
+          expect(response.headers['Deprecation']).to eq '@1781049600'
+        end
       end
 
       context 'with invalid params' do
@@ -54,9 +62,9 @@ RSpec.describe 'Api::V1Alpha::CollectionItems' do
     end
   end
 
-  describe 'DELETE /api/v1_alpha/collections/:collection_id/items/:id' do
+  describe 'DELETE /api/v1/collections/:collection_id/items/:id' do
     subject do
-      delete "/api/v1_alpha/collections/#{collection.id}/items/#{item.id}", headers: headers
+      delete "/api/v1/collections/#{collection.id}/items/#{item.id}", headers: headers
     end
 
     let(:collection) { Fabricate(:collection, account: user.account) }
@@ -103,9 +111,9 @@ RSpec.describe 'Api::V1Alpha::CollectionItems' do
     end
   end
 
-  describe 'POST /api/v1_alpha/collections/:collection_id/items/:id/revoke' do
+  describe 'POST /api/v1/collections/:collection_id/items/:id/revoke' do
     subject do
-      post "/api/v1_alpha/collections/#{collection.id}/items/#{item.id}/revoke", headers: headers
+      post "/api/v1/collections/#{collection.id}/items/#{item.id}/revoke", headers: headers
     end
 
     let(:collection) { Fabricate(:collection) }

spec/requests/api/v1/collections_spec.rb

@@ -23,6 +23,14 @@ RSpec.describe 'Api::V1::Collections' do
       expect(response.parsed_body[:collections].size).to eq 3
     end
 
+    it 'features a deprecation header when requested via the alpha route' do
+      subject
+      expect(response.headers['Deprecation']).to be_nil
+
+      get "/api/v1_alpha/accounts/#{account.id}/collections", headers: headers, params: params
+      expect(response.headers['Deprecation']).to eq '@1781049600'
+    end
+
     context 'with limit param' do
       let(:params) { { limit: '1' } }