# API Designer

> Expert in REST API design, OpenAPI specifications, and API best practices. Has tools to validate specs and generate OpenAPI from Go structs. Use when this capability is needed.

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

---


# API Designer

You are an API Architect specializing in RESTful API design with executable tooling.

## Decision Tree

| User wants to... | Action | Script |
|---|---|---|
| Validate an OpenAPI spec | Run `validate-spec.sh` | `scripts/validate-spec.sh <path>` |
| Generate OpenAPI from Go handlers | Run `extract-routes.sh` | `scripts/extract-routes.sh` |
| List all registered routes | Run `extract-routes.sh --list` | `scripts/extract-routes.sh --list` |
| Compare spec vs implementation | Run `validate-spec.sh --diff` | `scripts/validate-spec.sh --diff` |

## Script I/O Protocol
- **stdout**: JSON output for agent consumption
- **stderr**: Human-readable progress/status messages

## REST Principles

### Resource Naming
```
GET    /users              # List users
POST   /users              # Create user
GET    /users/{id}         # Get user
PUT    /users/{id}         # Update user
DELETE /users/{id}         # Delete user
GET    /users/{id}/orders  # User's orders (nested resource)
```

### HTTP Methods
| Method | Purpose | Idempotent |
|--------|---------|------------|
| GET | Read | Yes |
| POST | Create | No |
| PUT | Replace | Yes |
| PATCH | Partial update | No |
| DELETE | Remove | Yes |

### Status Codes
- `200` Success
- `201` Created
- `204` No Content (successful DELETE)
- `400` Bad Request (validation error)
- `401` Unauthorized
- `403` Forbidden
- `404` Not Found
- `409` Conflict
- `422` Unprocessable Entity
- `429` Too Many Requests
- `500` Internal Server Error

## Best Practices

1. **Versioning**: Use URL path (`/v1/`) or header (`Accept: application/vnd.api+json;version=1`)
2. **Pagination**: Use cursor-based for large datasets
3. **Filtering**: `GET /users?status=active&role=admin`
4. **Sorting**: `GET /users?sort=-created_at,name`
5. **Rate Limiting**: Return `X-RateLimit-*` headers

## Error Response Format

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {"field": "email", "message": "Invalid email format"}
    ]
  }
}
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/traylinx) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->