api-design-expert
Expert guide for designing robust APIs: REST best practices, GraphQL, gRPC, tRPC, OpenAPI/Swagger, API versioning, rate limiting, and contract-first design / Panduan ahli untuk merancang API yang kuat: praktik terbaik REST, GraphQL, gRPC, tRPC, OpenAPI/Swagger, versioning API, rate limiting, dan desain contract-first.
roedyrustam · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add roedyrustam/vibes-plug --skill api-design-expert技能说明
name: api-design-expert description: "Expert guide for designing robust APIs: REST best practices, GraphQL, gRPC, tRPC, OpenAPI/Swagger, API versioning, rate limiting, and contract-first design / Panduan ahli untuk merancang API yang kuat: praktik terbaik REST, GraphQL, gRPC, tRPC, OpenAPI/Swagger, versioning API, rate limiting, dan desain contract-first." author: "Roedy Rustam"
version: "3.0.0"
API Design Expert
English
Description
Expert guide for designing, documenting, and evolving production-grade APIs. Covers REST resource modeling and HTTP semantics, GraphQL schema design, gRPC with protobuf, and tRPC for end-to-end type-safe APIs in TypeScript monorepos. Includes OpenAPI 3.1 documentation, API versioning strategies, rate limiting, idempotency, and contract-first development workflows.
Trigger Conditions
- Designing a new API from scratch (REST, GraphQL, gRPC, or tRPC).
- Evolving an existing API without breaking clients.
- Documenting APIs with OpenAPI/Swagger.
- Implementing rate limiting, throttling, or idempotency.
- Choosing between REST, GraphQL, gRPC, and tRPC.
- Designing webhook systems.
- Implementing API authentication (API keys, JWT, OAuth2).
API Protocol Selection Guide
| Criteria | REST | GraphQL | gRPC | tRPC |
|---|---|---|---|---|
| Type Safety | Manual (OpenAPI) | Schema-enforced | Protobuf | End-to-end TS |
| Performance | Good | Good | Excellent (HTTP/2) | Good |
| Browser Support | Native | Native | Needs proxy | TS/JS only |
| Streaming | SSE / WebSocket | Subscriptions | Native bi-directional | SSE |
| Best For | Public APIs, mobile | Complex data graphs | Microservice-to-service | Next.js full-stack |
| Tooling | Universal | Rich ecosystem | Strong (Go, Java) | Next.js / Expo |
REST API Design Principles
Resource Naming Conventions
Collection: GET /api/v1/posts
Item: GET /api/v1/posts/{id}
Sub-resource:GET /api/v1/posts/{id}/comments
Action: POST /api/v1/posts/{id}/publish (use sparingly)
AVOID: /api/v1/getPosts, /api/v1/createPost, /api/v1/deletePost/{id}
HTTP Method Semantics
| Method | Idempotent | Safe | Use Case |
|---|---|---|---|
GET | Yes | Yes | Retrieve resources |
POST | No | No | Create resources, trigger actions |
PUT | Yes | No | Replace entire resource |
PATCH | No | No | Partial update |
DELETE | Yes | No | Remove resource |
Consistent Response Structure
// Success response
{
"data": { "id": "usr_01", "email": "user@example.com" },
"meta": { "requestId": "req_xyz", "timestamp": "2026-01-01T00:00:00Z" }
}
// Paginated list response
{
"data": [...],
"meta": {
"total": 1234,
"page": 2,
"pageSize": 20,
"hasNextPage": true,
"nextCursor": "eyJpZCI6"
}
}
// Error response (RFC 9457 Problem Details)
{
"type": "https://api.example.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "The 'email' field must be a valid email address.",
"instance": "/api/v1/users",
"errors": [
{ "field": "email", "message": "Invalid email format" }
]
}
HTTP Status Codes — Correct Usage
200 OK — Successful GET, PUT, PATCH
201 Created — Successful POST (include Location header)
204 No Content — Successful DELETE
400 Bad Request — Invalid request body or params
401 Unauthorized— Missing or invalid authentication
403 Forbidden — Authenticated but not authorized
404 Not Found — Resource not found
409 Conflict — Duplicate key, version conflict
422 Unprocessable Entity — Validation failure
429 Too Many Requests — Rate limit exceeded (include Retry-After)
500 Internal Server Error— Unexpected server error
API Versioning Strategies
Strategy 1 — URL Path (Recommended for public APIs):
GET /api/v1/users
GET /api/v2/users
Strategy 2 — Header:
GET /api/users
Accept: application/vnd.example.v2+json
Strategy 3 — Query Parameter (Avoid in production):
GET /api/users?version=2
Rules for non-breaking changes (no version bump needed):
- Adding new optional fields to responses.
- Adding new optional request parameters.
- Adding new endpoints.
Breaking changes (require new version):
- Removing or renaming fields.
- Changing field types.
- Changing error response structure.
tRPC — End-to-End Type Safety
// server/router.ts
import { initTRPC, TRPCError } from '@trpc/server';
import { z } from 'zod';
const t = initTRPC.context<Context>().create();
export const router = t.router;
export const publicProcedure = t.procedure;
export const protectedProcedure = t.procedure.use(({ ctx, next }) => {
if (!ctx.session?.user) throw new TRPCError({ code: 'UNAUTHORIZED' });
return next({ ctx: { ...ctx, user: ctx.session.user } });
});
export const appRouter = router({
users: router({
list: publicProcedure
.input(z.object({ page: z.number().int().min(1).default(1) }))
.query(async ({ input, ctx }) => {
return ctx.db.user.findMany({ skip: (input.page - 1) * 20, take: 20 });
}),
create: protectedProcedure
.input(z.object({ email: z.string().email(), name: z.string().min(2) }))
.mutation(async ({ input, ctx }) => {
return ctx.db.user.create({ data: input });
}),
}),
});
export type AppRouter = typeof appRouter;
// Client automatically infers all types — no code generation needed
Rate Limiting Implementation
// Sliding window rate limit with Redis (using Upstash)
import { Ratelimit } from '@upstash/ratelimit';
import { Redis } from '@upstash/redis';
const ratelimit = new Ratelimit({
r
阅读完整来源 ↗