About

Imported from shipshitdev/skills (skills/api-design-expert/SKILL.md). Install upstream with npx skills add shipshitdev/skills --skill api-design-expert. Copyright stays with the author.

API Design Expert Skill

Name: api-design-expert
Author: shipshitdev

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:

Check .agents/memory/ for API patterns and architecture notes
Review existing controllers and DTOs
Check for OpenAPI/Swagger setup
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

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/shipshitdev-skills-api-design-expert/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

shipshitdev-skills-api-design-expert.ocm.jsonjson

{
  "ocm": "1",
  "id": "shipshitdev-skills-api-design-expert",
  "kind": "skill",
  "name": "api-design-expert",
  "description": "Expert in RESTful API design, OpenAPI/Swagger documentation, versioning, error handling, and API best practices for NestJS applications. Use when designing API endpoints, building RESTful APIs, writing OpenAPI/Swagger docs, implementing versioning, or designing error responses and DTOs.",
  "publisher": "shipshitdev",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "coding"
    ],
    "tags": [
      "skill-md",
      "api",
      "rest",
      "design",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Expert in RESTful API design, OpenAPI/Swagger documentation, versioning, error handling, and API best practices for NestJS applications. Use when designing API endpoints, building RESTful APIs, writing OpenAPI/Swagger docs, implementing versioning, or designing error responses and DTOs."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/shipshitdev/skills",
      "path": "skills/api-design-expert/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/shipshitdev/skills/blob/HEAD/skills/api-design-expert/SKILL.md",
      "key": "shipshitdev/skills/skills/api-design-expert/SKILL.md"
    }
  },
  "instructions": "# API Design Expert Skill\n\n## When to Use\n\n- Designing new API endpoints\n- Creating RESTful APIs\n- Writing OpenAPI/Swagger documentation\n- Implementing API versioning\n- Designing error responses\n- Creating DTOs and validation\n- Implementing pagination, filtering, sorting\n\n## Project Context Discovery\n\nBefore providing guidance:\n\n1. Check `.agents/memory/` for API patterns and architecture notes\n2. Review existing controllers and DTOs\n3. Check for OpenAPI/Swagger setup\n4. Review versioning strategy\n\n## Core Principles\n\n### RESTful Design\n\n```typescript\n// Use nouns, plural, hierarchical\nGET    ",
  "cost": {
    "context_tokens": 431
  }
}

Fetch it by URL: GET /api/v1/registry/shipshitdev-skills-api-design-expert/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.