القائمة
REST/GraphQL/gRPC/tRPC API design patterns. Use when designing APIs, writing OpenAPI specs, versioning, auth, or rate limiting.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Builds multi-repo context hubs and compiled markdown knowledge maps. Use when profiling repo portfolios or assembling LLM-ready cross-repo knowledge bases.
Builds per-repo code graphs in JSON and markdown-ready derived artifacts. Use when you need blast radius, symbol-level maps, import graphs, inheritance, or test links.
Context-driven AI development with AGENTS.md, repo knowledge bases, Claude Code, Codex, and Copilot. Use when adopting repo-native AI workflows or multi-repo setups.
Technical writing for READMEs, ADRs, API docs, and changelogs. Use when revising or consolidating a repo documentation folder.
Design, implement, and troubleshoot NUKE-based CI/CD pipelines for .NET services with fast local-to-CI feedback loops. Use when creating or refactoring `nuke/Build.cs` target graphs, tuning `DependsOn`/`After`/`Triggers`/`OnlyWhenDynamic` behavior, orchestrating unit/API/DB test categories, merging and publishing coverage and test reports, building and pushing Docker images with traceable tags and digests, producing artifact contracts such as `deploy.env`, and diagnosing flaky or slow pipeline execution. For service code changes use $software-csharp-backend, for NUnit fixture design use $qa-testing-nunit, and for safe logging rewrites use $dev-structured-logs.
Systematic debugging for crashes, regressions, flakes, and production bugs. Use when diagnosing stack traces, logs, traces, or profiling data.
| name | dev-api-design |
| description | REST/GraphQL/gRPC/tRPC API design patterns. Use when designing APIs, writing OpenAPI specs, versioning, auth, or rate limiting. |
Use this skill to design, implement, and document production-grade APIs (REST, GraphQL, gRPC, and tRPC). Apply it for contract design (OpenAPI), versioning/deprecation, authentication/authorization, rate limiting, pagination, error models, and developer documentation.
Modern best practices (Jan 2026): HTTP semantics and cacheability (RFC 9110), Problem Details error model (RFC 9457), OpenAPI 3.1+, contract-first + breaking-change detection, strong AuthN/Z boundaries, explicit versioning/deprecation, and operable-by-default APIs (idempotency, rate limits, observability, trace context).
| Task | Pattern/Tool | Key Elements | When to Use |
|---|---|---|---|
| Design REST API | RESTful Design | Nouns (not verbs), HTTP methods, proper status codes | Resource-based APIs, CRUD operations |
| Version API | URL Versioning | /api/v1/resource, /api/v2/resource | Breaking changes, client migration |
| Paginate results | Cursor-Based | cursor=eyJpZCI6MTIzfQ&limit=20 | Real-time data, large collections |
| Handle errors | RFC 9457 Problem Details | type, title, status, detail, errors[] | Consistent error responses |
| Authenticate | JWT Bearer | Authorization: Bearer <token> | Stateless auth, microservices |
| Rate limit | Token Bucket | X-RateLimit-* headers, 429 responses | Prevent abuse, fair usage |
| Document API | OpenAPI 3.1 | Swagger UI, Redoc, code samples | Interactive docs, client SDKs |
| Flexible queries | GraphQL | Schema-first, resolvers, DataLoader | Client-driven data fetching |
| High-performance | gRPC + Protobuf | Binary protocol, streaming | Internal microservices |
| TypeScript-first | tRPC | End-to-end type safety, no codegen | Monorepos, internal tools |
| AI agent APIs | REST + MCP | Agent experience, machine-readable | LLM/agent consumption |
User needs: [API Type]
├─ Public API for third parties?
│ └─ REST with OpenAPI docs (broad compatibility)
│
├─ Internal microservices?
│ ├─ High throughput required? → **gRPC** (binary, fast)
│ └─ Simple CRUD? → **REST** (easy to debug)
│
├─ TypeScript monorepo (frontend + backend)?
│ └─ **tRPC** (end-to-end type safety, no codegen)
│
├─ Client needs flexible queries?
│ ├─ Real-time updates? → **GraphQL Subscriptions** or **WebSockets**
│ └─ Complex data fetching? → **GraphQL** (avoid over-fetching)
│
├─ Mobile/web clients?
│ ├─ Many entity types? → **GraphQL** (single endpoint)
│ └─ Simple resources? → **REST** (cacheable)
│
├─ AI agents consuming API?
│ └─ REST + **MCP** wrapper (agent experience)
│
└─ Streaming or bidirectional?
└─ **gRPC** (HTTP/2 streaming) or **WebSockets**
Resource: references/restful-design-patterns.md
Resource: references/pagination-filtering.md
_gt, _contains, _in)-created_at)Resource: references/error-handling-patterns.md
Resource: references/authentication-patterns.md
Resource: references/rate-limiting-patterns.md
X-RateLimit-*)Production-ready, copy-paste API implementations with authentication, database, validation, and docs.
FastAPI (Python): assets/fastapi/fastapi-complete-api.md
Express.js (Node/TypeScript): assets/express-nodejs/express-complete-api.md
Django REST Framework: assets/django-rest/django-rest-complete-api.md
Spring Boot (Java): assets/spring-boot/spring-boot-complete-api.md
| Anti-Pattern | Problem | Fix |
|---|---|---|
| Instant deprecation | Breaks clients | 90-day minimum sunset period |
| Action endpoints | Inconsistent API | Use resources + HTTP verbs |
| Version in body | Hard to route, debug | Version in URL or header |
| Generic errors | Poor DX | Specific error codes + messages |
| No rate limit headers | Clients can't back off | Include X-RateLimit-* |
| Tenant ID in URL only | Forgery risk | Validate against auth token |
| Leaky abstractions | Tight coupling | Design stable contracts |
Note: AI tools assist but contracts need human review.
See data/sources.json for:
This skill works best when combined with other specialized skills:
For the agent:
Success Criteria: APIs are discoverable, consistent, well-documented, secure, and follow HTTP/GraphQL semantics correctly.
If a user asks for "best" tools/frameworks, "latest" standards, or whether something is still relevant in 2026, do a quick web search using whatever browsing/search tool is available in the current environment. If web access is unavailable, answer from stable principles, state assumptions (traffic, latency, team skills, ecosystem), and avoid overstating currency.