Designing APIs

designing-apis

Design clean, consistent APIs. Use when creating new endpoints, defining contracts, or improving API ergonomics. Covers REST, versioning, and error handling.

majiayu000/claude-skill-registry·0installs663starsProductivity & Planning

SKILL.md

Full skill instructions

Designing APIs

Workflows

Resources: Identify resources and relationships
Endpoints: Define URL structure and methods
Request/Response: Define payloads and schemas
Errors: Define error responses
Document: Create OpenAPI spec

REST Principles

Resource Naming

Use nouns, not verbs: /users not /getUsers
Use plural: /users not /user
Use kebab-case: /user-profiles not /userProfiles
Nest for relationships: /users/{id}/orders

HTTP Methods

Method	Purpose	Idempotent
GET	Read	Yes
POST	Create	No
PUT	Replace	Yes
PATCH	Update	Yes
DELETE	Remove	Yes

Status Codes

Code	Meaning
200	Success
201	Created
204	No Content
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
422	Unprocessable Entity
500	Internal Server Error

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

Versioning

URL Versioning (Recommended)

GET /api/v1/users
GET /api/v2/users

Header Versioning

GET /api/users
Accept: application/vnd.api+json;version=1

Pagination

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "total_pages": 5
  }
}

OpenAPI Example

openapi: 3.0.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

Install skill

Copy and run in your terminal

npx -y skills add https://github.com/majiayu000/claude-skill-registry --skill designing-apis

View on GitHub

skills/data/designing-apis/SKILL.md

More Productivity & Planning skills

View all

Productivity & Planning

brainstorming

Structured design dialogue that validates ideas before implementation begins.

295.4K 385.7K

View

Productivity & Planning

ui-ux-pro-max

Comprehensive design intelligence for web and mobile UI/UX across 10 technology stacks.

133.1K 383.9K

View

Productivity & Planning

writing-plans

Comprehensive implementation plans for multi-step tasks, breaking down specs into bite-sized, testable steps.

295.4K 268K

View

Productivity & Planning

using-superpowers

Introduction to the obra skills system with mandatory skill invocation rules and best practices.

295.4K 259.8K

View

Productivity & Planning

executing-plans

Execute a written implementation plan with critical review and task checkpoints.

295.4K 229.1K

View

Productivity & Planning

dispatching-parallel-agents

Delegate independent tasks to specialized agents working concurrently with isolated context.

295.4K 206.3K

View

Productivity & Planning

using-git-worktrees

Isolated git worktrees with smart directory selection and safety verification.

295.4K 205.2K

View

Productivity & Planning

Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.

179.7K 170.6K

View