mcpField
A
api-design-expert

api-design-expert

github.com/shipshitdevDevelopment38203 installsUpdated 2d ago
Repository

About api-design-expert

An API-design guidance skill for developers creating or maintaining APIs. It covers REST conventions, response and error formats, versioning, validation, and documentation practices.

Key features

  1. 01REST endpoint design
  2. 02HTTP status code guidance
  3. 03Response and error formats
  4. 04DTO validation patterns
  5. 05Versioning and OpenAPI practices

Use cases

  1. 01Planning API endpoints
  2. 02Standardizing error responses
  3. 03Designing paginated list APIs
  4. 04Documenting APIs with OpenAPI

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/shipshitdev/skills --skill api-design-expert

After installing, type/api-design-expertin Claude Code to confirm it loaded.

Bundled filesplugin.jsonreferences/full-guide.md

Details

From the project README

API Design Expert Skill

When to Use

  • Designing new API endpoints
  • Creating RESTful APIs
  • Writing OpenAPI/Swagger documentation
  • Implementing API versioning
  • Designing error responses
  • Creating DTOs and validation
  • Implementing pagination, filtering, sorting

Project Context Discovery

Before providing guidance:

  1. Check .agents/memory/ for API patterns and architecture notes
  2. Review existing controllers and DTOs
  3. Check for OpenAPI/Swagger setup
  4. Review versioning strategy

Core Principles

RESTful Design
// Use nouns, plural, hierarchical
GET    /api/users
GET    /api/users/:id
POST   /api/users
PUT    /api/users/:id
DELETE /api/users/:id
GET    /api/users/:id/posts
HTTP Status Codes
  • 200 OK / 201 Created / 204 No Content
  • 400 Bad Request / 401 Unauthorized / 403 Forbidden
  • 404 Not Found / 409 Conflict / 500 Internal Server Error
Response Format
// Single resource
{ "data": {...}, "meta": {...} }

// List with pagination
{ "data": [...], "pagination": { "page", "limit", "total" } }
Error Format
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [...],
    "timestamp": "...",
    "path": "/api/users"
  }
}

Best Practices

  • Consistent naming conventions
  • Validate all inputs with DTOs
  • OpenAPI/Swagger documentation
  • Authentication on all endpoints
  • Pagination for lists
  • Version APIs from the start

For complete DTO examples, pagination/filtering/sorting patterns, versioning strategies, OpenAPI setup, CRUD controller patterns, nested resources, bulk operations, and anti-patterns, see: references/full-guide.md

Comments

Markdown supported