api-designer
Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards.
- License 许可
- MIT
- 最近更新
- 2026-09-20
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- api-designer
- license
- MIT
- metadata
- { "role": "architect", "scope": "design", "author": "https://github.com/Jeffallan", "domain": "api-architecture", "version": "1.1.0", "triggers": "API design, REST API, OpenAPI, API specification, API architecture, resource modeling, API versioning, GraphQL schema, API documentation", "output-format": "specification", "related-skills": "graphql-architect, fastapi-expert, nestjs-expert, spring-boot-engineer, security-reviewer" }
- description
- Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards.
02 资源文件 5
- 参考文档references/error-handling.md11.3 KB
- 参考文档references/openapi.md16.0 KB
- 参考文档references/pagination.md9.4 KB
- 参考文档references/rest-patterns.md7.3 KB
- 参考文档references/versioning.md7.8 KB
03 SKILL.md 正文
API Designer
Senior API architect specializing in REST and GraphQL APIs with comprehensive OpenAPI 3.1 specifications.
Core Workflow
- Analyze domain — Understand business requirements, data models, and client needs
- Model resources — Identify resources, relationships, and operations; sketch entity diagram before writing any spec
- Design endpoints — Define URI patterns, HTTP methods, request/response schemas
- Specify contract — Create OpenAPI 3.1 spec; validate before proceeding:
npx @redocly/cli lint openapi.yaml - Mock and verify — Spin up a mock server to test contracts:
npx @stoplight/prism-cli mock openapi.yaml - Plan evolution — Design versioning, deprecation, and backward-compatibility strategy
Reference Guide
Load detailed guidance based on context:
| Topic | Reference | Load When |
|---|---|---|
| REST Patterns | references/rest-patterns.md |
Resource design, HTTP methods, HATEOAS |
| Versioning | references/versioning.md |
API versions, deprecation, breaking changes |
| Pagination | references/pagination.md |
Cursor, offset, keyset pagination |
| Error Handling | references/error-handling.md |
Error responses, RFC 7807, status codes |
| OpenAPI | references/openapi.md |
OpenAPI 3.1, documentation, code generation |
Constraints
MUST DO
- Follow REST principles (resource-oriented, proper HTTP methods)
- Use consistent naming conventions (snake_case or camelCase — pick one, apply everywhere)
- Include comprehensive OpenAPI 3.1 specification
- Design proper error responses with actionable messages (RFC 7807)
- Implement pagination for all collection endpoints
- Version APIs with clear deprecation policies
- Document authentication and authorization
- Provide request/response examples
MUST NOT DO
- Use verbs in resource URIs (use
/users/{id}, not/getUser/{id}) - Return inconsistent response structures
- Skip error code documentation
- Ignore HTTP status code semantics
- Design APIs without a versioning strategy
- Expose implementation details in the API surface
- Create breaking changes without a migration path
- Omit rate limiting considerations
Templates
OpenAPI 3.1 Resource Endpoint (copy-paste starter)
openapi: "3.1.0"
info:
title: Example API
version: "1.1.0"
paths:
/users:
get:
summary: List users
operationId: listUsers
tags: [Users]
parameters:
- name: cursor
in: query
schema: { type: string }
description: Opaque cursor for pagination
- name: limit
in: query
schema: { type: integer, default: 20, maximum: 100 }
responses:
"200":
description: Paginated list of users
content:
application/json:
schema:
type: object
required: [data, pagination]
properties:
data:
type: array
items: { $ref: "#/components/schemas/User" }
pagination:
$ref: "#/components/schemas/CursorPage"
"400": { $ref: "#/components/responses/BadRequest" }
"401": { $ref: "#/components/responses/Unauthorized" }
"429": { $ref: "#/components/responses/TooManyRequests" }
/users/{id}:
get:
summary: Get a user
operationId: getUser
tags: [Users]
parameters:
- name: id
in: path
required: true
schema: { type: string, format: uuid }
responses:
"200":
description: User found
content:
application/json:
schema: { $ref: "#/components/schemas/User" }
"404": { $ref: "#/components/responses/NotFound" }
components:
schemas:
User:
type: object
required: [id, email, created_at]
properties:
id: { type: string, format: uuid, readOnly: true }
email: { type: string, format: email }
name: { type: string }
created_at: { type: string, format: date-time, readOnly: true }
CursorPage:
type: object
required: [next_cursor, has_more]
properties:
next_cursor: { type: string, nullable: true }
has_more: { type: boolean }
Problem: # RFC 7807 Problem Details
type: object
required: [type, title, status]
properties:
type: { type: string, format: uri, example: "https://api.example.com/errors/validation-error" }
title: { type: string, example: "Validation Error" }
status: { type: integer, example: 400 }
detail: { type: string, example: "The 'email' field must be a valid email address." }
instance: { type: string, format: uri, example: "/users/req-abc123" }
responses:
BadRequest:
description: Invalid request parameters
content:
application/problem+json:
schema: { $ref: "#/components/schemas/Problem" }
Unauthorized:
description: Missing or invalid authentication
content:
application/problem+json:
schema: { $ref: "#/components/schemas/Problem" }
NotFound:
description: Resource not found
content:
application/problem+json:
schema: { $ref: "#/components/schemas/Problem" }
TooManyRequests:
description: Rate limit exceeded
headers:
Retry-After: { schema: { type: integer } }
content:
application/problem+json:
schema: { $ref: "#/components/schemas/Problem" }
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- BearerAuth: []
RFC 7807 Error Response (copy-paste)
{
"type": "https://api.example.com/errors/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'email' field must be a valid email address.",
"instance": "/users/req-abc123",
"errors": [
{ "field": "email", "message": "Must be a valid email address." }
]
}
- Always use
Content-Type: application/problem+jsonfor error responses. typemust be a stable, documented URI — never a generic string.detailmust be human-readable and actionable.- Extend with
errors[]for field-level validation failures.
Output Checklist
When delivering an API design, provide:
- Resource model and relationships (diagram or table)
- Endpoint specifications with URIs and HTTP methods
- OpenAPI 3.1 specification (YAML)
- Authentication and authorization flows
- Error response catalog (all 4xx/5xx with
typeURIs) - Pagination and filtering patterns
- Versioning and deprecation strategy
- Validation result:
npx @redocly/cli lint openapi.yamlpasses with no errors
Knowledge Reference
REST architecture, OpenAPI 3.1, GraphQL, HTTP semantics, JSON:API, HATEOAS, OAuth 2.0, JWT, RFC 7807 Problem Details, API versioning patterns, pagination strategies, rate limiting, webhook design, SDK generation
04 同仓库更多 Skills
skill-creator
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
gsap-scrolltrigger
Official GSAP skill for ScrollTrigger — scroll-linked animations, pinning, scrub, triggers. Use when building or recommending scroll-based animation, parallax, pinned sections, or when the user asks about ScrollTrigger, scroll animations, or pinning. Recommend GSAP for scroll-driven animation when no library is specified.
frontend-design
Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
firecrawl-website-design-clone
Extract any website's design system into an agent-ready DESIGN.md using Firecrawl scrape evidence. Use when the user wants colors, fonts, spacing, components, layout patterns, or brand/UI guidance from a website so AI agents can create new websites, clone a look, or build pages inspired by that design.
canvas-design
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.
redis-core
Core Redis modeling guidance — choose the right data structure (String, Hash, List, Set, Sorted Set, JSON, Stream, Vector Set) and use consistent colon-separated key names. Use when designing a Redis data model, caching objects, deciding between Hash and JSON, building counters, leaderboards, membership sets, or session stores, or when reviewing/cleaning up Redis key naming.