api-design ยท diff

git:20260923.82a4143 to git:20260923.ffaa29c

1 added, 1 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: api-design
- description: RESTful and GraphQL API design: OpenAPI specs, pagination, rate limiting, error schemas, versioning, and backwards compatibility.
+ description: "RESTful and GraphQL API design: OpenAPI specs, pagination, rate limiting, error schemas, versioning, and backwards compatibility."
---
# API Design Skill
Design clean, consistent, and maintainable APIs.
## RESTful Design Principles
- Use nouns for resources, HTTP verbs for actions
- Consistent URL patterns: `/resources/{id}/sub-resources`
- Proper HTTP status codes (200, 201, 204, 400, 401, 403, 404, 409, 422, 500)
- Stateless: each request contains all needed info
- HATEOAS: include links for discoverability
## API Response Schema
```json
{
"data": {},
"meta": { "page": 1, "per_page": 20, "total": 100 },
"links": { "self": "...", "next": "...", "prev": "..." },
"errors": []
}
```
## Error Schema
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Human-readable description",
"details": [{"field": "email", "issue": "invalid format"}]
}
}
```
## Key Patterns
- **Pagination**: cursor-based for large datasets, offset for small
- **Filtering**: query params `?status=active&created_after=2024-01-01`
- **Sorting**: `?sort=-created_at,name`
- **Rate Limiting**: 429 + Retry-After header
- **Versioning**: URL path (`/v2/`) or header
- **Idempotency**: idempotency keys for safe retries