api-versioning

Name: api-versioning
Author: ThibautBaissac

39installs79forks

How to install api-versioning?

thibautbaissac/rails_ai_agents/api-versioning

$npx -y skills add ThibautBaissac/rails_ai_agents --skill api-versioning

Installs into the current project.

Summary

Implements RESTful API design with versioning and request specs. Use when building APIs, adding API endpoints, versioning APIs, or when user mentions REST, JSON API, or API design. WHEN NOT: Internal-only endpoints, HTML views, Turbo Stream responses, or APIs without external con

Files · 1

View on GitHub

SKILL.md

1	# API Versioning for Rails
2
3	## Overview
4
5	Well-structured APIs need versioning for backwards compatibility and clear organization.
6
7	## Versioning Strategies
8
9	\| Strategy \| URL Example \| Header Example \|
10	\|----------\|-------------\|----------------\|
11	\| URL Path \| `/api/v1/users` \| - \|
12	\| Query Param \| `/api/users?version=1` \| - \|
13	\| Header \| `/api/users` \| `Accept: application/vnd.api+json; version=1` \|
14	\| Accept Header \| `/api/users` \| `Accept: application/vnd.myapp.v1+json` \|
15
16	Recommended: URL Path versioning (most common, easiest to understand)
17
18	## Quick Setup
19
20	### Routes
21
22	```ruby
23	# config/routes.rb
24	Rails.application.routes.draw do
25	namespace :api do
26	namespace :v1 do
27	resources :users, only: [:index, :show, :create, :update, :destroy]
28	resources :posts, only: [:index, :show, :create]
29	end
30
31	# v2 with changes
32	namespace :v2 do
33	resources :users, only: [:index, :show, :create, :update, :destroy]
34	end
35	end
36	end
37	```
38
39	### Directory Structure
40
41	```
42	app/controllers/
43	├── api/
44	│ ├── base_controller.rb # Shared API logic
45	│ ├── v1/
46	│ │ ├── base_controller.rb # V1 base
47	│ │ ├── users_controller.rb
48	│ │ └── posts_controller.rb
49	│ └── v2/
50	│ ├── base_controller.rb # V2 base
51	│ └── users_controller.rb
52	```
53
54	### Base Controller
55
56	```ruby
57	# app/controllers/api/base_controller.rb
58	module Api
59	class BaseController < ApplicationController
60	# Skip CSRF for API requests
61	skip_before_action :verify_authenticity_token
62
63	# Respond with JSON by default
64	respond_to :json
65
66	# Handle common errors
67	rescue_from ActiveRecord::RecordNotFound, with: :not_found
68	rescue_from ActiveRecord::RecordInvalid, with: :unprocessable_entity
69	rescue_from ActionController::ParameterMissing, with: :bad_request
70
71	private
72
73	def not_found(exception)
74	render json: { error: exception.message }, status: :not_found
75	end
76
77	def unprocessable_entity(exception)
78	render json: { errors: exception.record.errors }, status: :unprocessable_entity
79	end
80
81	def bad_request(exception)
82	render json: { error: exception.message }, status: :bad_request
83	end
84	end
85	end
86	```
87
88	### Version Base Controller
89
90	```ruby
91	# app/controllers/api/v1/base_controller.rb
92	module Api
93	module V1
94	class BaseController < Api::BaseController
95	# V1-specific configuration
96	end
97	end
98	end
99	```
100
101	### Resource Controller
102
103	```ruby
104	# app/controllers/api/v1/users_controller.rb
105	module Api
106	module V1
107	class UsersController < BaseController
108	before_action :set_user, only: [:show, :update, :destroy]
109
110	def index
111	@users = User.page(params[:page]).per(25)
112	render json: {
113	data: @users,
114	meta: pagination_meta(@users)
115	}
116	end
117
118	def show
119	render json: { data: @user }
120	end
121
122	def create
123	@user = User.create!(user_params)
124	render json: { data: @user }, status: :created
125	end
126
127	def update
128	@user.update!(user_params)
129	render json: { data: @user }
130	end
131
132	def destroy
133	@user.destroy
134	head :no_content
135	end
136
137	private
138
139	def set_user
140	@user = User.find(params[:id])
141	end
142
143	def user_params
144	params.require(:user).permit(:name, :email)
145	end
146
147	def pagination_meta(collection)
148	{
149	current_page: collection.current_page,
150	total_pages: collection.total_pages,
151	total_count: collection.total_count
152	}
153	end
154	end
155	end
156	end
157	```
158
159	## Response Format
160
161	### Standard JSON Response
162
163	```json
164	{
165	"data": {
166	"id": 1,
167	"type": "user",
168	"attributes": {
169	"name": "John Doe",
170	"email": "john@example.com",
171	"created_at": "2024-01-15T10:30:00Z"
172	}
173	}
174	}
175	```
176
177	### Collection Response
178
179	```json
180	{
181	"data": [
182	{ "id": 1, "type": "user", "attributes": { ... } },
183	{ "id": 2, "type": "user", "attributes": { ... } }
184	],
185	"meta": {
186	"current_page": 1,
187	"total_pages": 10,
188	"total_count": 100
189	}
190	}
191	```
192
193	### Error Response
194
195	```json
196	{
197	"error": "Record not found",
198	"code": "not_found"
199	}
200
201	{
202	"errors": {
203	"email": ["has already been taken"],
204	"name": ["can't be blank"]
205	}
206	}
207	```
208
209	## Testing APIs
210
211	### Request Spec Template
212
213	```ruby
214	# spec/requests/api/v1/users_spec.rb
215	require 'rails_helper'
216
217	RSpec.describe 'Api::V1::Users', type: :request do
218	let(:headers) { { 'Accept' => 'application/json', 'Content-Type' => 'application/json' } }
219
220	describe 'GET /api/v1/users' do
221	let!(:users) { create_list(:user, 3) }
222
223	it 'returns all users' do
224	get '/api/v1/users', header

People who liked this also viewed

6 picks

Type

api-versioning

39installs79forks

View on GitHub

How to install api-versioning?

thibautbaissac/rails_ai_agents/api-versioning

$npx -y skills add ThibautBaissac/rails_ai_agents --skill api-versioning

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# API Versioning for Rails
2
3	## Overview
4
5	Well-structured APIs need versioning for backwards compatibility and clear organization.
6
7	## Versioning Strategies
8
9	\| Strategy \| URL Example \| Header Example \|
10	\|----------\|-------------\|----------------\|
11	\| URL Path \| `/api/v1/users` \| - \|
12	\| Query Param \| `/api/users?version=1` \| - \|
13	\| Header \| `/api/users` \| `Accept: application/vnd.api+json; version=1` \|
14	\| Accept Header \| `/api/users` \| `Accept: application/vnd.myapp.v1+json` \|
15
16	Recommended: URL Path versioning (most common, easiest to understand)
17
18	## Quick Setup
19
20	### Routes
21
22	```ruby
23	# config/routes.rb
24	Rails.application.routes.draw do
25	namespace :api do
26	namespace :v1 do
27	resources :users, only: [:index, :show, :create, :update, :destroy]
28	resources :posts, only: [:index, :show, :create]
29	end
30
31	# v2 with changes
32	namespace :v2 do
33	resources :users, only: [:index, :show, :create, :update, :destroy]
34	end
35	end
36	end
37	```
38
39	### Directory Structure
40
41	```
42	app/controllers/
43	├── api/
44	│ ├── base_controller.rb # Shared API logic
45	│ ├── v1/
46	│ │ ├── base_controller.rb # V1 base
47	│ │ ├── users_controller.rb
48	│ │ └── posts_controller.rb
49	│ └── v2/
50	│ ├── base_controller.rb # V2 base
51	│ └── users_controller.rb
52	```
53
54	### Base Controller
55
56	```ruby
57	# app/controllers/api/base_controller.rb
58	module Api
59	class BaseController < ApplicationController
60	# Skip CSRF for API requests
61	skip_before_action :verify_authenticity_token
62
63	# Respond with JSON by default
64	respond_to :json
65
66	# Handle common errors
67	rescue_from ActiveRecord::RecordNotFound, with: :not_found
68	rescue_from ActiveRecord::RecordInvalid, with: :unprocessable_entity
69	rescue_from ActionController::ParameterMissing, with: :bad_request
70
71	private
72
73	def not_found(exception)
74	render json: { error: exception.message }, status: :not_found
75	end
76
77	def unprocessable_entity(exception)
78	render json: { errors: exception.record.errors }, status: :unprocessable_entity
79	end
80
81	def bad_request(exception)
82	render json: { error: exception.message }, status: :bad_request
83	end
84	end
85	end
86	```
87
88	### Version Base Controller
89
90	```ruby
91	# app/controllers/api/v1/base_controller.rb
92	module Api
93	module V1
94	class BaseController < Api::BaseController
95	# V1-specific configuration
96	end
97	end
98	end
99	```
100
101	### Resource Controller
102
103	```ruby
104	# app/controllers/api/v1/users_controller.rb
105	module Api
106	module V1
107	class UsersController < BaseController
108	before_action :set_user, only: [:show, :update, :destroy]
109
110	def index
111	@users = User.page(params[:page]).per(25)
112	render json: {
113	data: @users,
114	meta: pagination_meta(@users)
115	}
116	end
117
118	def show
119	render json: { data: @user }
120	end
121
122	def create
123	@user = User.create!(user_params)
124	render json: { data: @user }, status: :created
125	end
126
127	def update
128	@user.update!(user_params)
129	render json: { data: @user }
130	end
131
132	def destroy
133	@user.destroy
134	head :no_content
135	end
136
137	private
138
139	def set_user
140	@user = User.find(params[:id])
141	end
142
143	def user_params
144	params.require(:user).permit(:name, :email)
145	end
146
147	def pagination_meta(collection)
148	{
149	current_page: collection.current_page,
150	total_pages: collection.total_pages,
151	total_count: collection.total_count
152	}
153	end
154	end
155	end
156	end
157	```
158
159	## Response Format
160
161	### Standard JSON Response
162
163	```json
164	{
165	"data": {
166	"id": 1,
167	"type": "user",
168	"attributes": {
169	"name": "John Doe",
170	"email": "john@example.com",
171	"created_at": "2024-01-15T10:30:00Z"
172	}
173	}
174	}
175	```
176
177	### Collection Response
178
179	```json
180	{
181	"data": [
182	{ "id": 1, "type": "user", "attributes": { ... } },
183	{ "id": 2, "type": "user", "attributes": { ... } }
184	],
185	"meta": {
186	"current_page": 1,
187	"total_pages": 10,
188	"total_count": 100
189	}
190	}
191	```
192
193	### Error Response
194
195	```json
196	{
197	"error": "Record not found",
198	"code": "not_found"
199	}
200
201	{
202	"errors": {
203	"email": ["has already been taken"],
204	"name": ["can't be blank"]
205	}
206	}
207	```
208
209	## Testing APIs
210
211	### Request Spec Template
212
213	```ruby
214	# spec/requests/api/v1/users_spec.rb
215	require 'rails_helper'
216
217	RSpec.describe 'Api::V1::Users', type: :request do
218	let(:headers) { { 'Accept' => 'application/json', 'Content-Type' => 'application/json' } }
219
220	describe 'GET /api/v1/users' do
221	let!(:users) { create_list(:user, 3) }
222
223	it 'returns all users' do
224	get '/api/v1/users', header

People who liked this also viewed

6 picks

Type