api-patterns

Name: api-patterns
Author: ThibautBaissac

635stars79forks

How to install api-patterns?

thibautbaissac/rails_ai_agents/api-patterns

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

Installs into the current project.

Summary

Builds REST APIs using respond_to blocks with Jbuilder templates following the 37signals same-controllers-different-formats philosophy. Use when adding API endpoints, JSON responses, token authentication, pagination, or when user mentions API, JSON, REST, or Jbuilder. WHEN NOT: F

Files · 1

View on GitHub

SKILL.md

1	# API Patterns
2
3	## Philosophy: Same Controllers, Different Formats
4
5	- One controller serves both HTML (web) and JSON (API)
6	- Use `respond_to` blocks for format-specific responses
7	- RESTful routes only (no GraphQL, no custom endpoints unless necessary)
8	- Jbuilder for JSON templates (like ERB for HTML)
9	- HTTP status codes for success/errors
10	- Token-based authentication for API (not OAuth unless required)
11
12	## Project Knowledge
13
14	Stack: Jbuilder for JSON views, RESTful routes, token-based API auth,
15	same controllers for HTML and JSON, HTTP caching with ETags for API.
16
17	Multi-tenancy: API uses same account scoping (`/accounts/:account_id/...`),
18	token scoped to account.
19
20	Commands:
21	```bash
22	# Generate API token model
23	rails generate model ApiToken user:references account:references \
24	token:string last_used_at:datetime
25
26	# Test API endpoints
27	curl -H "Authorization: Bearer TOKEN" \
28	-H "Accept: application/json" \
29	http://localhost:3000/boards
30	```
31
32	## Pattern 1: Respond To Blocks
33
34	```ruby
35	class BoardsController < ApplicationController
36	before_action :set_board, only: [:show, :edit, :update, :destroy]
37
38	def index
39	@boards = Current.account.boards.includes(:creator).order(created_at: :desc)
40
41	respond_to do \|format\|
42	format.html # renders index.html.erb
43	format.json # renders index.json.jbuilder
44	end
45	end
46
47	def show
48	respond_to do \|format\|
49	format.html
50	format.json
51	end
52	end
53
54	def create
55	@board = Current.account.boards.build(board_params)
56	@board.creator = Current.user
57
58	respond_to do \|format\|
59	if @board.save
60	format.html { redirect_to @board, notice: "Board created" }
61	format.json { render :show, status: :created, location: @board }
62	else
63	format.html { render :new, status: :unprocessable_entity }
64	format.json { render json: @board.errors, status: :unprocessable_entity }
65	end
66	end
67	end
68
69	def update
70	respond_to do \|format\|
71	if @board.update(board_params)
72	format.html { redirect_to @board, notice: "Board updated" }
73	format.json { render :show, status: :ok }
74	else
75	format.html { render :edit, status: :unprocessable_entity }
76	format.json { render json: @board.errors, status: :unprocessable_entity }
77	end
78	end
79	end
80
81	def destroy
82	@board.destroy
83
84	respond_to do \|format\|
85	format.html { redirect_to boards_path, notice: "Board deleted" }
86	format.json { head :no_content }
87	end
88	end
89
90	private
91
92	def set_board
93	@board = Current.account.boards.find(params[:id])
94	end
95
96	def board_params
97	params.require(:board).permit(:name, :description)
98	end
99	end
100	```
101
102	## Pattern 2: Jbuilder Templates
103
104	See @references/jbuilder-templates.md for full details.
105
106	```ruby
107	# app/views/boards/index.json.jbuilder
108	json.array! @boards do \|board\|
109	json.extract! board, :id, :name, :description, :created_at, :updated_at
110	json.creator do
111	json.extract! board.creator, :id, :name, :email
112	end
113	json.url board_url(board, format: :json)
114	end
115
116	# app/views/boards/show.json.jbuilder
117	json.extract! @board, :id, :name, :description, :created_at, :updated_at
118	json.creator do
119	json.extract! @board.creator, :id, :name, :email
120	end
121	json.cards @board.cards, partial: "cards/card", as: :card
122	json.url board_url(@board, format: :json)
123
124	# app/views/cards/_card.json.jbuilder
125	json.extract! card, :id, :title, :description, :created_at, :updated_at
126	json.creator do
127	json.extract! card.creator, :id, :name
128	end
129	json.url board_card_url(card.board, card, format: :json)
130	```
131
132	## Pattern 3: API Token Authentication
133
134	See @references/api-auth.md for full details.
135
136	```ruby
137	# app/models/api_token.rb
138	class ApiToken < ApplicationRecord
139	belongs_to :user
140	belongs_to :account
141
142	has_secure_token :token, length: 32
143
144	validates :name, presence: true
145	validates :token, presence: true, uniqueness: true
146
147	scope :active, -> { where(active: true) }
148
149	def use!
150	touch(:last_used_at)
151	end
152	end
153
154	# app/controllers/concerns/api_authenticatable.rb
155	module ApiAuthenticatable
156	extend ActiveSupport::Concern
157
158	included do
159	before_action :authenticate_from_token, if: :api_request?
160	end
161
162	private
163
164	def api_request?
165	request.format.json?
166	end
167
168	def authenticate_from_token
169	token = request.headers["Authorization"]
170	&.match(/Bearer (.+)/)&.captures&.first
171
172	if token
173	@api_token = ApiToken.active.find_by(token: token)
174	if @api_token
175	@api_token.use!
176	Current.user = @api_token.user
177	Current.acc

People who liked this also viewed

6 picks

Type

api-patterns

635stars79forks

View on GitHub

How to install api-patterns?

thibautbaissac/rails_ai_agents/api-patterns

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# API Patterns
2
3	## Philosophy: Same Controllers, Different Formats
4
5	- One controller serves both HTML (web) and JSON (API)
6	- Use `respond_to` blocks for format-specific responses
7	- RESTful routes only (no GraphQL, no custom endpoints unless necessary)
8	- Jbuilder for JSON templates (like ERB for HTML)
9	- HTTP status codes for success/errors
10	- Token-based authentication for API (not OAuth unless required)
11
12	## Project Knowledge
13
14	Stack: Jbuilder for JSON views, RESTful routes, token-based API auth,
15	same controllers for HTML and JSON, HTTP caching with ETags for API.
16
17	Multi-tenancy: API uses same account scoping (`/accounts/:account_id/...`),
18	token scoped to account.
19
20	Commands:
21	```bash
22	# Generate API token model
23	rails generate model ApiToken user:references account:references \
24	token:string last_used_at:datetime
25
26	# Test API endpoints
27	curl -H "Authorization: Bearer TOKEN" \
28	-H "Accept: application/json" \
29	http://localhost:3000/boards
30	```
31
32	## Pattern 1: Respond To Blocks
33
34	```ruby
35	class BoardsController < ApplicationController
36	before_action :set_board, only: [:show, :edit, :update, :destroy]
37
38	def index
39	@boards = Current.account.boards.includes(:creator).order(created_at: :desc)
40
41	respond_to do \|format\|
42	format.html # renders index.html.erb
43	format.json # renders index.json.jbuilder
44	end
45	end
46
47	def show
48	respond_to do \|format\|
49	format.html
50	format.json
51	end
52	end
53
54	def create
55	@board = Current.account.boards.build(board_params)
56	@board.creator = Current.user
57
58	respond_to do \|format\|
59	if @board.save
60	format.html { redirect_to @board, notice: "Board created" }
61	format.json { render :show, status: :created, location: @board }
62	else
63	format.html { render :new, status: :unprocessable_entity }
64	format.json { render json: @board.errors, status: :unprocessable_entity }
65	end
66	end
67	end
68
69	def update
70	respond_to do \|format\|
71	if @board.update(board_params)
72	format.html { redirect_to @board, notice: "Board updated" }
73	format.json { render :show, status: :ok }
74	else
75	format.html { render :edit, status: :unprocessable_entity }
76	format.json { render json: @board.errors, status: :unprocessable_entity }
77	end
78	end
79	end
80
81	def destroy
82	@board.destroy
83
84	respond_to do \|format\|
85	format.html { redirect_to boards_path, notice: "Board deleted" }
86	format.json { head :no_content }
87	end
88	end
89
90	private
91
92	def set_board
93	@board = Current.account.boards.find(params[:id])
94	end
95
96	def board_params
97	params.require(:board).permit(:name, :description)
98	end
99	end
100	```
101
102	## Pattern 2: Jbuilder Templates
103
104	See @references/jbuilder-templates.md for full details.
105
106	```ruby
107	# app/views/boards/index.json.jbuilder
108	json.array! @boards do \|board\|
109	json.extract! board, :id, :name, :description, :created_at, :updated_at
110	json.creator do
111	json.extract! board.creator, :id, :name, :email
112	end
113	json.url board_url(board, format: :json)
114	end
115
116	# app/views/boards/show.json.jbuilder
117	json.extract! @board, :id, :name, :description, :created_at, :updated_at
118	json.creator do
119	json.extract! @board.creator, :id, :name, :email
120	end
121	json.cards @board.cards, partial: "cards/card", as: :card
122	json.url board_url(@board, format: :json)
123
124	# app/views/cards/_card.json.jbuilder
125	json.extract! card, :id, :title, :description, :created_at, :updated_at
126	json.creator do
127	json.extract! card.creator, :id, :name
128	end
129	json.url board_card_url(card.board, card, format: :json)
130	```
131
132	## Pattern 3: API Token Authentication
133
134	See @references/api-auth.md for full details.
135
136	```ruby
137	# app/models/api_token.rb
138	class ApiToken < ApplicationRecord
139	belongs_to :user
140	belongs_to :account
141
142	has_secure_token :token, length: 32
143
144	validates :name, presence: true
145	validates :token, presence: true, uniqueness: true
146
147	scope :active, -> { where(active: true) }
148
149	def use!
150	touch(:last_used_at)
151	end
152	end
153
154	# app/controllers/concerns/api_authenticatable.rb
155	module ApiAuthenticatable
156	extend ActiveSupport::Concern
157
158	included do
159	before_action :authenticate_from_token, if: :api_request?
160	end
161
162	private
163
164	def api_request?
165	request.format.json?
166	end
167
168	def authenticate_from_token
169	token = request.headers["Authorization"]
170	&.match(/Bearer (.+)/)&.captures&.first
171
172	if token
173	@api_token = ApiToken.active.find_by(token: token)
174	if @api_token
175	@api_token.use!
176	Current.user = @api_token.user
177	Current.acc

People who liked this also viewed

6 picks

Type