跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

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 | Bahasa Indonesia


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

CriteriaRESTGraphQLgRPCtRPC
Type SafetyManual (OpenAPI)Schema-enforcedProtobufEnd-to-end TS
PerformanceGoodGoodExcellent (HTTP/2)Good
Browser SupportNativeNativeNeeds proxyTS/JS only
StreamingSSE / WebSocketSubscriptionsNative bi-directionalSSE
Best ForPublic APIs, mobileComplex data graphsMicroservice-to-serviceNext.js full-stack
ToolingUniversalRich ecosystemStrong (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

MethodIdempotentSafeUse Case
GETYesYesRetrieve resources
POSTNoNoCreate resources, trigger actions
PUTYesNoReplace entire resource
PATCHNoNoPartial update
DELETEYesNoRemove 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
阅读完整来源 ↗