api-design
Guide for designing and documenting RESTful APIs. Use when asked to design an API, create endpoints, or document an API.
소스 정보
- 저장소
- microsoft/haste
- 최근 소스 활동
- 2026년 6월 17일 22:19
- 감지된 SKILL.md 언어
- 영어
- 스타
- 109
- 포크
- 19
설치 방법
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
소스 파일 검토
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
SKILL.md 표시 중
SKILL.md
소스 지침 · 읽기 전용 미리보기- name
- api-design
- description
- Guide for designing and documenting RESTful APIs. Use when asked to design an API, create endpoints, or document an API.
- source
- Internal engineering practices, REST API conventions
- domain
- architecture
- level
- intermediate
- agents
- ["backend-dev","gis"]
- created_date
- 2026-04-27
- last_validated
- validated_by
- status
- draft
# API Design
## Overview
Standards and patterns for designing consistent, well-documented RESTful APIs. Covers naming, HTTP methods, error handling, status codes, and documentation requirements.
## Key Concepts
### Naming Conventions
- Plural nouns for resources: `/users`, `/orders`, `/products`
- Kebab-case for multi-word: `/user-profiles`
- Nest related resources: `/users/{id}/orders`
- Query params for filtering: `/users?role=admin&active=true`
### HTTP Methods
| Method | Purpose | Idempotent | Response |
|--------|---------|------------|----------|
| GET | Read | Yes | 200 + body |
| POST | Create | No | 201 + body + Location |
| PUT | Replace | Yes | 200 + body |
| PATCH | Partial update | No | 200 + body |
| DELETE | Remove | Yes | 204 (no body) |
### Error Response Format
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Human-readable description",
"details": [
{"field": "email", "message": "Invalid email format"}
]
}
}
```
### Status Codes
- **200**: Success — **201**: Created — **204**: No content
- **400**: Bad request — **401**: Unauthorized — **403**: Forbidden
- **404**: Not found — **409**: Conflict — **422**: Unprocessable
- **429**: Rate limited — **500**: Internal error
## Decision Framework
| Scenario | Method | Path | Status |
|----------|--------|------|--------|
| List items | GET | /items | 200 |
| Get one item | GET | /items/{id} | 200 / 404 |
| Create item | POST | /items | 201 |
| Full update | PUT | /items/{id} | 200 / 404 |
| Partial update | PATCH | /items/{id} | 200 / 404 |
| Delete item | DELETE | /items/{id} | 204 / 404 |
| Search | GET | /items?q=term | 200 |
| Bulk action | POST | /items/batch | 200 / 207 |
## Documentation Requirements
Every endpoint must document:
1. HTTP method and path
2. Description
3. Request parameters (path, query, body) with types
4. Response schema with examples
5. Error codes and descriptions
6. Authentication requirements
## Common Pitfalls
- **Using verbs in URLs** — Use nouns: `/users` not `/getUsers`
- **Inconsistent error format** — Use the same error schema everywhere
- **Missing pagination** — Any list endpoint that can grow needs pagination
- **No versioning strategy** — Decide early: URL (`/v1/`) or header-based
GitHub에서 보기