api-design

Q: How do I install api-design?

Run npx skills add https://github.com/pixel-process-ug/superkit-agents --skill api-design in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/api-design/ (personal) or .claude/skills/api-design/ (project).

by pixel-process-ugBackend & APIs

Use when designing API endpoints, defining request/response schemas, generating OpenAPI specifications, choosing between REST/GraphQL/tRPC, or establishing API conventions for a project

Installs: 81
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/pixel-process-ug/superkit-agents --skill api-design

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads api-design automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

API Design

Overview

Structured API endpoint design through guided discovery. Produces consistent, well-documented API designs with OpenAPI/Swagger specifications. Covers resource modeling, authentication, pagination, error handling, and versioning — ensuring consumer-centric design before any implementation begins.

Announce at start: "I'm using the api-design skill to design the API."

Phase 1: Discovery

Ask these questions ONE AT A TIME:

Resource Questions

#	Question	What It Determines
1	What entities/resources does this API manage?	Resource naming
2	What are the relationships between them?	Nested routes, includes
3	What operations are needed for each? (CRUD, search, batch)	HTTP methods, endpoints

Consumer Questions

#	Question	What It Determines
4	Who will consume this API? (frontend, mobile, third-party, internal)	Response shape, auth model
5	What authentication/authorization is needed?	Security scheme
6	What rate limits or quotas apply?	Rate limiting headers

Constraint Questions

#	Question	What It Determines
7	REST, GraphQL, or tRPC?	API paradigm
8	Versioning strategy? (URL path, header, query param)	URL structure
9	Pagination approach? (cursor, offset, keyset)	List response shape
10	Existing API conventions in the codebase?	Consistency constraints

API Paradigm Decision Table

Factor	Choose REST	Choose GraphQL	Choose tRPC
Consumers	Multiple, diverse	Frontend-heavy, flexible queries	TypeScript monorepo
Caching needs	Strong (HTTP caching)	Moderate (client-side)	Low (internal only)
Data shape	Predictable, resource-oriented	Nested, variable-shape	Type-safe RPC
Team familiarity	Universal	Requires schema knowledge	Requires TypeScript
Real-time needs	WebSocket addon	Subscriptions built-in	Subscription support

STOP after discovery — present a summary of resources, operations, and constraints. Get confirmation before designing endpoints.

Phase 2: Design Endpoints

For each endpoint, define:

### [METHOD] /api/v1/[resource]

**Purpose:** [what this endpoint does]

**Request:**
- Headers: `Authorization: Bearer <token>`
- Query params: `?page=1&limit=20&sort=created_at:desc`
- Body:
  ```json
  {
    "field": "type — description"
  }

Response (200):

{
  "data": [...],
  "meta": { "total": 100, "page": 1, "limit": 20 }
}

Error Responses:

Status	Code	Description
400	VALIDATION_ERROR	Invalid request body
401	UNAUTHORIZED	Missing or invalid token
404	NOT_FOUND	Resource doesn't exist
409	CONFLICT	Resource already exists

Authorization: [who can access this]


### HTTP Method Decision Table

| Operation | Method | Status (success) | Idempotent |
|-----------|--------|-----------------|------------|
| List resources | GET | 200 | Yes |
| Get single resource | GET | 200 | Yes |
| Create resource | POST | 201 | No |
| Full replace | PUT | 200 | Yes |
| Partial update | PATCH | 200 | No |
| Delete resource | DELETE | 204 | Yes |
| Bulk create | POST | 201 | No |
| Search (complex) | POST | 200 | Yes (safe) |

### Pagination Decision Table

| Approach | When to Use | Pros | Cons |
|----------|------------|------|------|
| **Cursor** | Real-time feeds, large datasets | Consistent, no skipping | Cannot jump to page N |
| **Offset** | Small datasets, admin panels | Simple, jumpable | Skips/duplicates on insert |
| **Keyset** | Time-series, logs | Efficient on large tables | Requires sortable key |

### Error Response Format

All endpoints must use a consistent error shape:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}

Status Code Reference

Code	Meaning	When to Use
200	OK	Successful GET, PUT, PATCH
201	Created	Successful POST that creates
204	No Content	Successful DELETE
400	Bad Request	Validation failure
401	Unauthorized	Missing or invalid credentials
403	Forbidden	Valid credentials, insufficient permissions
404	Not Found	Resource does not exist
409	Conflict	Duplicate or state conflict
422	Unprocessable Entity	Valid JSON but semantic error
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server failure

STOP after endpoint design — present each endpoint for review and approval.

Phase 3: Generate OpenAPI Spec

openapi: 3.1.0
info:
  title: [API Name]
  version: 1.0.0
  description: [API description]

servers:
  - url: http://localhost:3000/api/v1
    description: Development
  - url: https://api.example.com/v1
    description: Production

paths:
  /resource:
    get:
      summary: List resources
      parameters: [...]
      responses: [...]
    post:
      summary: Create resource
      requestBody: [...]
      responses: [...]

components:
  schemas: [...]
  securitySchemes: [...]

STOP after spec generation — validate the YAML and present for final approval.

Phase 4: Save and Transition

After explicit approval:

Save OpenAPI spec to docs/api/YYYY-MM-DD-<api-name>.yaml
Commit with message: docs(api): add OpenAPI spec for <api-name>
Determine next step based on user intent

Transition Decision Table

User Intent	Next Skill	Rationale
"Let's implement this"	`planning`	Create implementation plan from API spec
"Write specs for this"	`spec-writing`	Behavioral specs for each endpoint
"Generate client SDK"	Manual	Use OpenAPI codegen tools
"Just save the design"	None	API design is the deliverable
"Add tests"	`testing-strategy`	Define API test approach

Design Principles

Principle	Rule
Consistent naming	Plural nouns for collections (`/users`, not `/user`)
Proper HTTP methods	GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes
Proper status codes	Use the right code for the right situation (see table above)
Consistent error format	Same error shape across all endpoints
Pagination by default	All list endpoints paginated
Filtering and sorting	Query params for list endpoints
Idempotency	PUT and DELETE are always idempotent
HATEOAS	Include links for discoverability (when appropriate)

Anti-Patterns / Common Mistakes

Mistake	Why It Is Wrong	What To Do Instead
Verb-based URLs (`/getUsers`)	Not RESTful, breaks conventions	Use nouns: `GET /users`
Inconsistent plural/singular	Confuses consumers	Always plural for collections
Returning 200 for errors	Hides failures from clients	Use proper status codes
No pagination on list endpoints	Performance bomb on large datasets	Always paginate
Different error formats per endpoint	Clients can't build generic error handling	One error shape for all
Exposing internal IDs in URLs	Security and coupling risk	Use UUIDs or slugs
No versioning strategy	Breaking changes break clients	Version from day one
Designing without knowing consumers	API serves no one well	Discovery phase first

Anti-Rationalization Guards

Do NOT skip the discovery phase — understand consumers and constraints first
Do NOT design endpoints without defining error responses
Do NOT skip pagination for any list endpoint
Do NOT use inconsistent naming across endpoints
Do NOT generate the OpenAPI spec without user approval of endpoint designs
Do NOT mix API paradigms (REST + GraphQL) without explicit justification

Integration Points

Skill	Relationship
`spec-writing`	Downstream: API design informs behavioral specifications
`planning`	Downstream: API endpoints become implementation tasks
`tech-docs-generator`	Downstream: OpenAPI spec feeds API reference docs
`testing-strategy`	Downstream: API design informs integration test strategy
`security-review`	Downstream: auth/authz model reviewed for vulnerabilities
`database-schema-design`	Upstream: data model informs resource design
`prd-generation`	Upstream: PRD requirements drive API resource identification

Verification Gate

Before claiming the API design is complete:

VERIFY all endpoints have request/response schemas
VERIFY all error responses are documented with consistent format
VERIFY authentication is specified for each endpoint
VERIFY pagination is defined for all list endpoints
VERIFY the OpenAPI spec is valid YAML
VERIFY user has approved each endpoint individually

Skill Type

Flexible — Adapt API paradigm, pagination style, and auth model to project needs while preserving the discovery-first approach, consistent error handling, and consumer-centric design principles.

FAQ

What does the api-design skill do?

Use when designing API endpoints, defining request/response schemas, generating OpenAPI specifications, choosing between REST/GraphQL/tRPC, or establishing API conventions for a project

How do I install api-design?

Run npx skills add https://github.com/pixel-process-ug/superkit-agents --skill api-design in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/api-design/ (personal) or .claude/skills/api-design/ (project).

Which AI agents can use api-design?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is api-design safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains api-design?

It is published by pixel-process-ug in pixel-process-ug/superkit-agents. It has 81 recorded installs.