A platform for community discussion. Free, open, simple.
# frozen_string_literal: true
require_relative "support"
module JsonApiKitSpec
class ChangedTopicsController < JsonApiKit::BaseController
resource :topics
end
class RenameTopicsPostedAtToCreatedAt < JsonApiKit::VersionChange
version "2026-10-01"
description "The `posted_at` attribute of the topics resource is renamed to `created_at`."
resource :topics do
renamed_attribute from: :posted_at, to: :created_at
renamed_attribute from: :words,
to: :title,
down: ->(title) { title.to_s.split(" ") },
up: ->(words) { words.to_a.join(" ") }
renamed_sort from: :bumped_at, to: :last_posted_at
renamed_filter from: :name, to: :title
end
end
end
RSpec.describe "JSON:API version changes", type: :request do
include_context "with a listing of topics"
let(:first_version) { JsonApiKit::Timeline::FIRST_RELEASE }
let(:version_change) { JsonApiKitSpec::RenameTopicsPostedAtToCreatedAt.new(__FILE__) }
let(:version_changes) { JsonApiKit::VersionChanges.new([version_change]) }
let(:change_version) { version_change.version }
let(:version) { first_version.to_s }
let(:parsed_body) { JSON.parse(response.body) }
let(:error) { parsed_body["errors"].sole }
let(:attributes) { parsed_body["data"].first["attributes"] }
let(:ids) { parsed_body["data"].map { it["id"] } }
before do
oldest.update_columns(last_posted_at: Time.utc(2026, 8, 3))
middle.update_columns(last_posted_at: Time.utc(2026, 8, 1))
newest.update_columns(last_posted_at: Time.utc(2026, 8, 2))
freeze_time(change_version.date + 1.day)
allow(JsonApiKit::VersionChanges).to receive(:core).and_return(version_changes)
Rails.application.routes.disable_clear_and_finalize = true
Rails.application.routes.draw do
get "/api/changed-topics" => "json_api_kit_spec/changed_topics#index"
end
Rails.application.routes.disable_clear_and_finalize = false
get "/api/changed-topics", headers: { "HTTP_API_VERSION" => version }, params: query
end
after { Rails.application.reload_routes! }
context "when the client is pinned before the change" do
it "sends the version of the pin" do
expect(response.headers["Api-Version"]).to eq(first_version.to_s)
end
it "sends the attributes under the names of that version" do
expect(attributes.keys).to contain_exactly("words", "postedAt")
end
it "sends a reshaped attribute in the shape of that version" do
expect(attributes["words"]).to eq(%w[Bands of a segmented listing])
end
context "when the request selects the reshaped field" do
let(:query) { { "fields" => { "topics" => "words" } } }
it "sends that field only" do
expect(attributes.keys).to contain_exactly("words")
end
end
context "when the request sorts by the reshaped field" do
let(:query) { { "sort" => "words" } }
it "orders the rows by that attribute" do
expect(ids).to eq([oldest.id.to_s, newest.id.to_s, middle.id.to_s])
end
end
context "when the request selects the renamed field" do
let(:query) { { "fields" => { "topics" => "postedAt" } } }
it "sends that field only" do
expect(attributes.keys).to contain_exactly("postedAt")
end
end
context "when the request sorts by the renamed field" do
let(:query) { { "sort" => "postedAt" } }
it "orders the rows by that attribute" do
expect(ids).to eq([oldest.id.to_s, middle.id.to_s, newest.id.to_s])
end
end
context "when the request anchors a window on the renamed field" do
let(:query) do
{
"sort" => "postedAt",
"page" => {
"anchor" => {
"postedAt" => middle.created_at.iso8601(6),
},
"beforeSize" => "1",
"afterSize" => "0",
},
}
end
it "sends the rows of the window" do
expect(ids).to eq([oldest.id.to_s, middle.id.to_s])
end
end
context "when the request anchors a window on the reshaped field" do
let(:query) do
{
"sort" => "words",
"page" => {
"anchor" => {
"words" => %w[Bands of a segmented listing],
},
"beforeSize" => "1",
"afterSize" => "0",
},
}
end
it "sends the rows of the window" do
expect(ids).to eq([oldest.id.to_s, newest.id.to_s])
end
end
context "when a refusal includes the renamed field" do
let(:query) do
{
"sort" => "words",
"page" => {
"anchor" => {
"postedAt" => middle.created_at.iso8601(6),
},
},
}
end
it "sends the name of that version" do
expect(error).to eq(
refusal(
title: "Anchor does not match the sort",
detail: "The anchor is postedAt, but this request sorts by words.",
parameter: "page[anchor][postedAt]",
).deep_stringify_keys,
)
end
end
context "when the request sorts by the renamed sort" do
let(:query) { { "sort" => "bumpedAt" } }
it "orders the rows by the current sort" do
expect(ids).to eq([middle.id.to_s, newest.id.to_s, oldest.id.to_s])
end
end
context "when the request sorts by the current name of the renamed sort" do
let(:query) { { "sort" => "lastPostedAt" } }
it "sends the reason" do
expect(error).to eq(
refusal(
title: "Invalid member name",
detail: "Use bumpedAt, not lastPostedAt.",
parameter: "sort",
).deep_stringify_keys,
)
end
end
context "when the request filters by the renamed filter" do
let(:query) { { "filter" => { "name" => newest.title } } }
it "sends the rows the current filter keeps" do
expect(ids).to eq([newest.id.to_s])
end
end
context "when a refusal includes the renamed sort" do
let(:query) do
{
"sort" => "bumpedAt",
"page" => {
"anchor" => {
"postedAt" => middle.created_at.iso8601(6),
},
},
}
end
it "sends the name of that version" do
expect(error).to eq(
refusal(
title: "Anchor does not match the sort",
detail: "The anchor is postedAt, but this request sorts by bumpedAt.",
parameter: "page[anchor][postedAt]",
).deep_stringify_keys,
)
end
end
context "when the request uses the new name" do
let(:query) { { "fields" => { "topics" => "createdAt" } } }
it { expect(response).to have_http_status(:bad_request) }
it "sends the reason" do
expect(error).to eq(
refusal(
title: "Invalid member name",
detail: "Use postedAt, not createdAt.",
parameter: "fields[topics]",
).deep_stringify_keys,
)
end
end
end
context "when the client is pinned between the first version and the change" do
let(:version) { (first_version.date + 1.day).to_s }
it "sends the first version" do
expect(response.headers["Api-Version"]).to eq(first_version.to_s)
end
it "sends the attributes under the names of the first version" do
expect(attributes.keys).to contain_exactly("words", "postedAt")
end
end
context "when the client is pinned at the change" do
let(:version) { change_version.to_s }
it "sends the version of the change" do
expect(response.headers["Api-Version"]).to eq(change_version.to_s)
end
it "sends the attributes under the names of that version" do
expect(attributes.keys).to contain_exactly("title", "createdAt")
end
context "when the request selects the field" do
let(:query) { { "fields" => { "topics" => "createdAt" } } }
it "sends that field only" do
expect(attributes.keys).to contain_exactly("createdAt")
end
end
context "when the request sorts by the current sort" do
let(:query) { { "sort" => "lastPostedAt" } }
it "orders the rows by that sort" do
expect(ids).to eq([middle.id.to_s, newest.id.to_s, oldest.id.to_s])
end
end
end
end