소스 정보
- 저장소
- vinilana/workshop-yungas
- 최근 소스 활동
- 2026년 3월 2일 18:43
- 감지된 SKILL.md 언어
- 영어
- 스타
- 0
- 포크
- 0
설치 방법
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
소스 파일 검토
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
SKILL.md 표시 중
SKILL.md
소스 지침 · 읽기 전용 미리보기- type
- skill
- name
- Api Design
- description
- Design RESTful APIs following best practices
- skillSlug
- api-design
- phases
- ["P","R"]
- generated
- 2026-03-02T00:00:00.000Z
- status
- filled
- scaffoldVersion
- 2.0.0
# API Design
## When to Use
Activate this skill when designing new API endpoints or reviewing existing ones. It ensures RESTful conventions, consistent response shapes, and proper HTTP semantics.
## Instructions
1. **Follow existing conventions**:
- Base path: `/api/` prefix for all endpoints.
- Resource naming: plural nouns (`/api/franchises`, not `/api/franchise`).
- Route constants: Define paths in `packages/shared/src/constants.ts` under `API_ROUTES`.
2. **HTTP methods**:
- `GET` — Read (list or single resource). Never mutate state.
- `POST` — Create a new resource. Return 201 with created entity.
- `PUT` — Full update of a resource.
- `PATCH` — Partial update of a resource.
- `DELETE` — Remove a resource.
3. **Response envelopes**:
- Success: `ApiResponse<T>` — `{ data: T, message?: string }`
- Error: `ApiErrorResponse` — `{ error: string, message?: string }`
4. **Status codes**:
- `200` — Successful read or update
- `201` — Successful creation
- `400` — Validation error (missing required fields, invalid data)
- `401` — Missing or invalid authentication token
- `404` — Resource not found
- `500` — Internal server error
5. **Query parameters**:
- `?search=term` — Full-text search across relevant fields
- `?page=1&limit=20` — Pagination (future)
- `?status=active` — Filtering (future)
6. **Input validation**:
- NestJS: Use `class-validator` decorators on DTO classes.
- Express: Manual validation checking required fields before processing.
- Always validate: `name` (required), `owner_name` (required), `email` (required, format).
7. **Legacy policy**: New API endpoints must be designed for NestJS only. The Express.js API is frozen (legacy) and should not receive new endpoints or features. Only critical bug fixes are permitted in the Express backend. Existing dual-implementation endpoints remain as-is, but new work targets NestJS exclusively.
## Examples
**Endpoint specification:**
```
POST /api/franchises
Authorization: Bearer <token>
Content-Type: application/json
Request:
{
"name": "Franchise São Paulo",
"ownerName": "Maria Silva",
"email": "maria@example.com",
"phone": "(11) 99999-0000",
"city": "São Paulo",
"state": "SP",
"status": "pending"
}
Response (201):
{
"data": {
"id": 11,
"name": "Franchise São Paulo",
"ownerName": "Maria Silva",
"email": "maria@example.com",
"phone": "(11) 99999-0000",
"address": null,
"city": "São Paulo",
"state": "SP",
"status": "pending",
"createdAt": "2026-03-02T12:00:00.000Z",
"updatedAt": "2026-03-02T12:00:00.000Z"
}
}
Response (400):
{
"error": "Validation failed",
"message": "name, ownerName, and email are required"
}
```
GitHub에서 보기