# API Design

> Design a RESTful API endpoint

- Skill: `sunnypatneedi/api-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sunnypatneedi/api-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sunnypatneedi/api-design/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: sunnypatneedi (https://skillmd.com/u/sunnypatneedi)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/sunnypatneedi/api-design

---


# API Design

Help me design a RESTful API:

## Requirements

1. **Resource**: What entity is this for?
2. **Operations**: What actions are needed (CRUD, other)?
3. **Relationships**: How does it relate to other resources?
4. **Users**: Who will call this API?

## Endpoint Design

For each operation, define:

### URL Structure

- Resource path (nouns, plural)
- Parameter placement
- Query parameters for filtering/sorting

### HTTP Methods

- GET for reads
- POST for creates
- PUT/PATCH for updates
- DELETE for removes

### Request Format

- Request body schema
- Required vs optional fields
- Validation rules

### Response Format

- Success response schema
- Pagination structure (if list)
- Error response format

### Status Codes

- 2xx for success
- 4xx for client errors
- 5xx for server errors

## Documentation

Generate OpenAPI/Swagger spec including:

- Endpoint descriptions
- Parameter definitions
- Schema definitions
- Example requests/responses

## Best Practices Check

Verify the design follows:

- RESTful conventions
- Consistent naming
- Proper status codes
- Security considerations