Skip to content
LiveNew tools this week
Submit
AIMarketly
api-designer logo

API Designer

api-designer

API architecture design and documentation for RESTful, GraphQL, and gRPC services. Creates OpenAPI specifications, defines versioning strategies, and establishes authentication/authorization patterns. Use when user asks to design API, create endpoints, document REST/GraphQL, or plan API architect...

JochenYang/Jochen-ai-rules0installs20starsDevOps & CI/CD

SKILL.md

Full skill instructions

API Designer

Design high-quality API interfaces and output standardized interface documentation and design specifications.

Core Capabilities

  • RESTful/​GraphQL/​gRPC architecture design
  • Unified naming conventions and error handling
  • OpenAPI/​Swagger documentation generation
  • API versioning and backward compatibility
  • Authentication, authorization, and rate limiting strategies

Quick Reference

HTTP Method Semantics

MethodPurposeIdempotent
GETRead resource✅
POSTCreate resource❌
PUTFull update✅
PATCHPartial update❌
DELETEDelete resource✅

Common Status Codes

  • 200 Success / 201 Created / 204 No Content
  • 400 Bad Request / 401 Unauthorized / 403 Forbidden / 404 Not Found
  • 500 Server Error

Design Principles

  1. Resource-Oriented: Use plural nouns in URLs, express actions with HTTP methods
  2. Unified Format: Consistent request/​response format, structured error messages
  3. Version Management: URL or Header version control, backward compatibility
  4. Security First: Authentication, authorization, input validation, rate limiting

Boundaries

Focus on API design and documentation standards, not specific business logic implementation.

When NOT to Use

  • Writing implementation code → use developer
  • Database schema design → use database-engineer
  • Frontend UI development → use frontend-design
  • Infrastructure or DevOps setup → use devops-engineer

When To Use

Use this skill when the user asks to:

  • design a new API or endpoint structure
  • document existing APIs with OpenAPI/​Swagger
  • plan API versioning or migration strategy
  • establish authentication/​authorization patterns for APIs

Quick Reference

Always run --help first to see usage.

  • scripts/​openapi-gen.sh - Generate OpenAPI documentation

Detailed References

  • ./​workflows/​api-design.md - API design workflow
  • ./​guides/​rest-api.md - REST API design guide
  • ./​guides/​graphql.md - GraphQL API design guide
  • ./​guides/​grpc.md - gRPC API design guide

Escalation Rules

Pause and ask the owner before:

  • locking in an API style, auth model, or versioning strategy that has broad product impact
  • expanding from interface design into implementation details outside this skill's boundary
  • making compatibility assumptions that could break existing clients

Final Output Contract (MANDATORY)

Every use of this skill should end with:

  1. Skill Fit - why API design work was needed
  2. Primary Deliverable - interface design, spec, or contract summary
  3. Execution Evidence - references used, files produced, and validation performed
  4. Risks / Open Questions - compatibility, auth, or rollout concerns
  5. Next Action - the concrete documentation, review, or implementation step