Copilot instructions

1---
2description: Rails API Guide
3applyTo: "app/controllers/api/**/*.rb"
4---
5 
6# Rails API Guide
7 
8## Core Philosophy
9 
10- Design APIs for longevity and stability
11- Version from the very beginning
12- Keep responses consistent and predictable
13- Document thoroughly and accurately
14- Build APIs that developers love to use
15 
16## API Design Principles
17 
18- Follow RESTful conventions strictly
19- Use standard HTTP methods appropriately
20- Return meaningful status codes
21- Keep endpoints focused and simple
22- Design for future extensibility
23 
24## Versioning Strategy
25 
26- Version APIs from day one
27- Use URL path versioning (/api/v1)
28- Never break backward compatibility
29- Deprecate gracefully with notices
30- Document version differences clearly
31 
32## Request Handling
33 
34- Accept JSON by default
35- Support content negotiation
36- Validate request formats
37- Handle malformed requests gracefully
38- Provide clear error messages
39 
40## Response Format
41 
42- Use consistent JSON structure
43- Include metadata when helpful
44- Implement sparse fieldsets
45- Support response filtering
46- Keep payloads minimal
47 
48## Authentication Methods
49 
50- Use token-based authentication
51- Implement OAuth when appropriate
52- Support API keys for simple cases
53- Never use session cookies for APIs
54- Document authentication clearly
55 
56## Authorization Patterns
57 
58- Check permissions for every endpoint
59- Use consistent authorization logic
60- Return proper 401/403 status codes
61- Implement role-based access
62- Audit API access patterns
63 
64## Error Handling
65 
66- Return consistent error format
67- Include error codes and messages
68- Provide debugging information in development
69- Log errors appropriately
70- Handle exceptions gracefully
71 
72## Status Codes
73 
74- Use standard HTTP status codes correctly
75- 200 OK for successful GET/PUT
76- 201 Created for successful POST
77- 204 No Content for successful DELETE
78- 422 Unprocessable Entity for validation errors
79 
80## Pagination
81 
82- Always paginate list endpoints
83- Use consistent pagination format
84- Include total count and page info
85- Support customizable page sizes
86- Consider cursor-based pagination
87 
88## Rate Limiting
89 
90- Implement rate limiting from start
91- Return rate limit headers
92- Use progressive throttling
93- Provide higher limits for authenticated users
94- Document rate limits clearly
95 
96## Filtering and Sorting
97 
98- Support field filtering
99- Implement sort parameters
100- Allow multiple sort fields
101- Use consistent parameter names
102- Document available options
103 
104## Serialization
105 
106- Use Active Model Serializers or similar
107- Keep serializers focused
108- Support nested resources carefully
109- Implement field selection
110- Cache serialized responses
111 
112## Documentation
113 
114- Document every endpoint
115- Include request/response examples
116- Specify required parameters
117- List possible error responses
118- Keep documentation updated
119 
120## Testing APIs
121 
122- Test all endpoints thoroughly
123- Verify authentication and authorization
124- Test error scenarios
125- Check response formats
126- Validate status codes
127 
128## Performance Optimization
129 
130- Implement response caching
131- Use ETags for conditional requests
132- Support compression
133- Optimize database queries
134- Monitor response times
135 
136## Webhooks
137 
138- Design webhook payloads carefully
139- Include event types
140- Implement retry logic
141- Sign webhook requests
142- Document webhook events
143 
144## CORS Configuration
145 
146- Configure CORS appropriately
147- Limit allowed origins
148- Specify allowed methods
149- Handle preflight requests
150- Document CORS policy
151 
152## API Security
153 
154- Always use HTTPS
155- Validate all input
156- Implement request signing
157- Audit API usage
158- Monitor for abuse
159 
160## Backward Compatibility
161 
162- Never remove fields
163- Add new fields as optional
164- Deprecate features gracefully
165- Maintain old versions
166- Communicate changes clearly
167 
168## API Monitoring
169 
170- Track response times
171- Monitor error rates
172- Log API usage patterns
173- Alert on anomalies
174- Review metrics regularly
175 
176## Client Libraries
177 
178- Provide SDKs when possible
179- Include code examples
180- Test client libraries
181- Version SDKs with API
182- Support multiple languages
183 
184## GraphQL Considerations
185 
186- Use GraphQL for complex queries
187- Implement proper authorization
188- Handle N+1 queries
189- Rate limit by complexity
190- Document schema thoroughly
191 
192## API Gateway Patterns
193 
194- Consider API gateway for microservices
195- Implement request routing
196- Handle authentication centrally
197- Add request/response transformation
198- Monitor gateway performance
199 
200## Development Workflow
201 
202- Use API-first design
203- Mock endpoints early
204- Test with real clients
205- Version control API specs
206- Review API changes carefully
207 
208## Common Patterns
209 
210- Resource-based URLs
211- Nested resources sparingly
212- Bulk operations support
213- Async processing for long operations
214- Webhook notifications
215 
216## Anti-Patterns to Avoid
217 
218- Exposing database structure
219- Inconsistent naming
220- Breaking changes without versioning
221- Poor error messages
222- Missing documentation
223 
224## API Standards
225 
226- Follow JSON:API or similar spec
227- Use ISO 8601 for dates
228- Implement UUID for identifiers
229- Support internationalization
230- Handle timezones properly
231 
232## Best Practices Summary
233 
234- Version from the start
235- Document thoroughly
236- Keep responses consistent
237- Monitor everything
238- Design for developers
239 
240Remember: APIs are forever. Design them carefully, version them properly, and never break backward compatibility.
241