api-patterns
API design, versioning, testing, schema validation, and contract testing patterns for REST and GraphQL APIs.
Install / Use
npx skills add vibeeval/vibecosystem --skill api-patternsInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
LegalSupported Platforms
Our assessment of api-patterns
api-patterns scores 84/100 on our quality scale, 139th of 210 Legal skills we index.
Its SKILL.md is 15 KB long, well organised into 21 sections with 14 code examples: a thorough specification that gives an agent plenty to work with.
It has 535 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated about 3 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
- Our last check on 2026-10-31 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 98/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-15. Automated pattern scan on 2026-10-15. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
api-patterns compared with similar skills
All 4 of these similar skills score higher than api-patterns; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| api-patterns (this skill)by vibeeval | 84 | 535 | 3mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 117.8k | 9d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.8k | 10d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 82.0k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.9k | today | CLAUDE.md |
Frequently asked questions
- How do I install api-patterns?
- Run
npx skills add vibeeval/vibecosystem --skill api-patterns. The install tabs above show the steps for each supported agent. - Which AI agents does api-patterns work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is api-patterns safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 98/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is api-patterns still maintained?
- The repository was last updated about 3 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
Skill content
View source on GitHubname: api-patterns description: API design, versioning, testing, schema validation, and contract testing patterns for REST and GraphQL APIs.
API Patterns
REST and GraphQL API design patterns for consistent, versioned, and well-tested interfaces.
API Versioning
URL-Based Versioning
// routes/v1/markets.ts
// routes/v2/markets.ts
// URL: /api/v1/markets, /api/v2/markets
// Express router setup
import { Router } from 'express'
const v1Router = Router()
const v2Router = Router()
app.use('/api/v1', v1Router)
app.use('/api/v2', v2Router)
// Deprecation header middleware
function deprecationWarning(version: string, sunsetDate: string) {
return (_req: Request, res: Response, next: NextFunction) => {
res.setHeader('Deprecation', 'true')
res.setHeader('Sunset', sunsetDate)
res.setHeader('Link', `</api/v${parseInt(version) + 1}>; rel="successor-version"`)
next()
}
}
v1Router.use(deprecationWarning('1', 'Sat, 01 Jan 2027 00:00:00 GMT'))
Header-Based Versioning
// Accept: application/vnd.api+json;version=2
function versionMiddleware(req: Request, res: Response, next: NextFunction) {
const accept = req.headers['accept'] || ''
const match = accept.match(/version=(\d+)/)
req.apiVersion = match ? parseInt(match[1]) : 1
next()
}
Schema Validation with Zod
Request + Response Validation
import { z } from 'zod'
// Request schema
const CreateMarketSchema = z.object({
name: z.string().min(1).max(200),
description: z.string().max(2000).optional(),
category: z.enum(['sports', 'politics', 'crypto', 'tech']),
closeAt: z.string().datetime(),
initialLiquidity: z.number().positive().max(1_000_000)
})
// Response schema - strip internal fields
const MarketResponseSchema = z.object({
id: z.string().uuid(),
name: z.string(),
category: z.string(),
status: z.enum(['open', 'closed', 'resolved']),
volume: z.number(),
createdAt: z.string().datetime()
})
type CreateMarketDto = z.infer<typeof CreateMarketSchema>
type MarketResponse = z.infer<typeof MarketResponseSchema>
// Validation middleware
function validate<T>(schema: z.ZodSchema<T>) {
return (req: Request, res: Response, next: NextFunction) => {
const result = schema.safeParse(req.body)
if (!result.success) {
return res.status(400).json({
success: false,
error: 'Validation failed',
code: 'VALIDATION_ERROR',
details: result.error.flatten()
})
}
req.validated = result.data
next()
}
}
// Usage
router.post('/markets', validate(CreateMarketSchema), async (req, res) => {
const dto = req.validated as CreateMarketDto
const market = await marketService.create(dto)
const response = MarketResponseSchema.parse(market)
res.status(201).json({ success: true, data: response })
})
Standardized Error Responses
// Always: { success, error, code, details? }
interface ApiError {
success: false
error: string
code: string
details?: unknown
requestId?: string
}
interface ApiSuccess<T> {
success: true
data: T
meta?: { total?: number; page?: number; limit?: number }
}
const ERROR_CODES = {
VALIDATION_ERROR: 400,
UNAUTHORIZED: 401,
FORBIDDEN: 403,
NOT_FOUND: 404,
CONFLICT: 409,
RATE_LIMITED: 429,
INTERNAL: 500
} as const
function apiError(
res: Response,
code: keyof typeof ERROR_CODES,
message: string,
details?: unknown
): Response {
return res.status(ERROR_CODES[code]).json({
success: false,
error: message,
code,
details,
requestId: res.locals.requestId
} satisfies ApiError)
}
Pagination Patterns
Cursor-Based Pagination (Recommended for large datasets)
interface CursorPage<T> {
items: T[]
nextCursor: string | null
prevCursor: string | null
hasMore: boolean
}
async function paginateWithCursor<T extends { id: string; createdAt: Date }>(
query: (cursor: string | null, limit: number) => Promise<T[]>,
cursor: string | null,
limit = 20
): Promise<CursorPage<T>> {
// Fetch one extra to detect hasMore
const items = await query(cursor, limit + 1)
const hasMore = items.length > limit
const page = hasMore ? items.slice(0, limit) : items
return {
items: page,
nextCursor: hasMore ? Buffer.from(page[page.length - 1].id).toString('base64') : null,
prevCursor: cursor,
hasMore
}
}
// GET /api/markets?cursor=<base64>&limit=20
router.get('/markets', async (req, res) => {
const cursor = req.query.cursor as string | null
const limit = Math.min(parseInt(req.query.limit as string) || 20, 100)
const decoded = cursor ? Buffer.from(cursor, 'base64').toString() : null
const page = await paginateWithCursor(
(c, l) => db.market.findMany({
take: l,
skip: c ? 1 : 0,
cursor: c ? { id: c } : undefined,
orderBy: { createdAt: 'desc' }
}),
decoded,
limit
)
res.json({ success: true, ...page })
})
Offset Pagination (Simple use cases)
interface OffsetPage<T> {
items: T[]
total: number
page: number
limit: number
totalPages: number
}
// GET /api/markets?page=2&limit=20
Rate Limiting
Token Bucket with Redis
import Redis from 'ioredis'
const redis = new Redis(process.env.REDIS_URL!)
async function tokenBucket(
key: string,
capacity: number,
refillRate: number // tokens per second
): Promise<{ allowed: boolean; remaining: number; resetIn: number }> {
const now = Date.now()
const bucketKey = `ratelimit:${key}`
const script = `
local key = KEYS[1]
local capacity = tonumber(ARGV[1])
local refill_rate = tonumber(ARGV[2])
local now = tonumber(ARGV[3])
local bucket = redis.call('HMGET', key, 'tokens', 'last_refill')
local tokens = tonumber(bucket[1]) or capacity
local last_refill = tonumber(bucket[2]) or now
local elapsed = (now - last_refill) / 1000
tokens = math.min(capacity, tokens + elapsed * refill_rate)
if tokens >= 1 then
tokens = tokens - 1
redis.call('HMSET', key, 'tokens', tokens, 'last_refill', now)
redis.call('EXPIRE', key, math.ceil(capacity / refill_rate) + 1)
return {1, math.floor(tokens)}
else
return {0, 0}
end
`
const [allowed, remaining] = await redis.eval(
script, 1, bucketKey, capacity, refillRate, now
) as [number, number]
return {
allowed: allowed === 1,
remaining,
resetIn: allowed ? 0 : Math.ceil(1 / refillRate)
}
}
function rateLimitMiddleware(capacity: number, refillRate: number) {
return async (req: Request, res: Response, next: NextFunction) => {
const key = req.user?.id || req.ip || 'anonymous'
const result = await tokenBucket(key, capacity, refillRate)
res.setHeader('X-RateLimit-Limit', capacity)
res.setHeader('X-RateLimit-Remaining', result.remaining)
if (!result.allowed) {
res.setHeader('Retry-After', result.resetIn)
return apiError(res, 'RATE_LIMITED', 'Too many requests')
}
next()
}
}
API Endpoint Testing
import { describe, it, expect, beforeAll, afterAll } from 'vitest'
import supertest from 'supertest'
import { app } from '../app'
import { db } from '../db'
const request = supertest(app)
describe('POST /api/v1/markets', () => {
let authToken: string
beforeAll(async () => {
authToken = await getTestToken()
})
it('creates a market with valid payload', async () => {
const payload = {
name: 'Will BTC reach 100k?',
category: 'crypto',
closeAt: new Date(Date.now() + 86400000).toISOString(),
initialLiquidity: 1000
}
const res = await request
.post('/api/v1/markets')
.set('Authorization', `Bearer ${authToken}`)
.send(payload)
.expect(201)
expect(res.body.success).toBe(true)
expect(res.body.data).toMatchObject({
id: expect.any(String),
name: payload.name,
status: 'open'
})
})
it('rejects invalid payload with 400', async () => {
const res = await request
.post('/api/v1/markets')
.set('Authorization', `Bearer ${authToken}`)
.send({ name: '' }) // invalid
.expect(400)
expect(res.body.success).toBe(false)
expect(res.body.code).toBe('VALIDATION_ERROR')
})
it('returns 401 without auth token', async () => {
const res = await request.post('/api/v1/markets').send({}).expect(401)
expect(res.body.code).toBe('UNAUTHORIZED')
})
})
Breaking Change Detection Checklist
Before releasing a new API version, verify:
BREAKING changes (require version bump):
[ ] Removed a field from response
[ ] Changed field type (string → number)
[ ] Renamed a field
[ ] Changed HTTP method
[ ] Removed an endpoint
[ ] Changed required → optional (ok) vs optional → required (breaking)
[ ] Changed error codes/format
NON-BREAKING changes (safe to ship):
[ ] Added new optional fields to response
[ ] Added new optional query parameters
[ ] Added new endpoints
[ ] Added new enum values (check client handling)
[ ] Relaxed validation rules
OpenAPI Spec Generation
// Use zod-to-openapi or tsoa
import { extendZodWithOpenApi } from 'zod-to-openapi'
import { z } from 'zod'
extendZodWithOpenApi(z)
const MarketSchema = z.object({
id: z.string().uuid().openapi({ example: 'abc-123' }),
name: z.string().openapi({ example: 'Will BTC hit 100k?' }),
status: z.enum(['open', 'closed', 'resolved'])
}).openapi('Market')
// Auto-generate spec at /api/docs.json
Plan-Based Authorization
Tier-Aware Middleware
enum PlanTier {
FREE = 'free',
PRO = 'pro',
ENTERPRISE = 'enterprise'
}
interface PlanLimits {
tier: PlanTier
rateLimit: number // requests per minute
maxItems: number // max resources
features: Set<string> // enabled features
}
const PLAN_LIMITS: Record<PlanTier, PlanLimits> = {
[PlanTier.FREE]: { tier: PlanTier.FREE, rateLimit: 60, maxItems: 100, features: new Set(['read']) },
[PlanTier.PRO]: { tier: PlanTier.PRO, rateLimit: 600, maxItems: 10_000, features: new Set(['read', 'write', 'export']) },
[PlanTier.ENTERPRISE]: { tier: PlanTier.ENTERPRISE, rateLimit: 6000, maxItems: Infinity, features: new Set(['read', 'write', 'export', 'audit', 'sso']) },
}
function requireFeature(feature: string) {
return (req: Request, res: Response, next: NextFunction) => {
const plan = PLAN_LIMITS[req.user.planTier as PlanTier]
if (!plan.features.has(feature)) {
return apiError(res, 'FORBIDDEN', `Feature "${feature}" requires ${PlanTier.PRO} plan or higher`)
}
next()
}
}
function requireQuota(countFn: (userId: string) => Promise<number>) {
return async (req: Request, res: Response, next: NextFunction) => {
const plan = PLAN_LIMITS[req.user.planTier as PlanTier]
const current = await countFn(req.user.id)
if (current >= plan.maxItems) {
return apiError(res, 'FORBIDDEN', `Plan limit reached (${plan.maxItems} items). Upgrade to increase.`)
}
next()
}
}
// Usage
router.post('/exports', requireFeature('export'), async (req, res) => { /* ... */ })
router.post('/projects', requireQuota(countUserProjects), async (req, res) => { /* ... */ })
Serverless Rate Limiting
Sliding Window without Redis
// In-memory sliding window — single-instance only
// WARNING: Resets on cold start (serverless). For production multi-instance,
// use Redis/Upstash. Add MAX_ENTRIES cap to prevent memory exhaustion from IP flooding.
const windows = new Map<string, number[]>()
function slidingWindowRateLimit(
key: string,
maxRequests: number,
windowMs: number
): { allowed: boolean; remaining: number; retryAfter: number } {
const now = Date.now()
const windowStart = now - windowMs
// Get or create timestamps array
const timestamps = windows.get(key) ?? []
const valid = timestamps.filter(t => t > windowStart)
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
117.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.8kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
82.0k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.9kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
