Most Rails APIs start as a format.json branch in an HTML controller and only become an API once a partner depends on them. This post lays out the structure to put in place before that: URL path versioning starting at /api/v1, an Api::BaseController < ActionController::API that owns auth, error envelopes and transaction tagging, and one thin base per version.

It compares bearer tokens stored as digests with Doorkeeper and JWTs, shows how to ship v2 without copying the v1 tree (versioned serializers and params, unchanged endpoints routed to the existing controller), and closes with retiring v1: RFC 9745 Deprecation and RFC 8594 Sunset headers, NRQL facets by client and endpoint, a zero-traffic alert, and a 410 after removal.