มันเริ่มต้นเป็นข้อความ Slack ไม่เป็นอันตรายที่ 4:30 PM ในวันศุกร์ 
 
 "Hey, frontend ต้องการจุดสิ้นสุดที่รวดเร็วเพื่อแสดงตัวเลือกของผู้ใช้ เพียงแค่กลับบล็อก JSON จาก DB ควรใช้เวลา 10 นาที" "Hey, frontend ต้องการจุดสิ้นสุดที่รวดเร็วเพื่อแสดงตัวเลือกของผู้ใช้ เพียงแค่กลับบล็อก JSON จาก DB ควรใช้เวลา 10 นาที" กว่าหกเดือนต่อมา "จุดสิ้นสุด 10 นาที" ได้กลายเป็นโมโนไลต์ เส้นทาง. มันกลับ 4MB ของข้อมูล, ผสม camelCase และ snake_case, ไม่มี pagination และแตกทุกครั้งที่คุณสัมผัสแผนภูมิฐานข้อมูล. คุณไม่ได้ออกแบบ API; คุณเพียงแค่เปิดเผยฐานข้อมูลของคุณผ่าน HTTP และหวังว่าดีที่สุด. /v1/user/stuff This is the silent killer of modern software scalability. เราพิจารณาการออกแบบ API เป็นความคิดหลัง - ภารกิจการท่อข้อมูลจาก A ไปยัง B. แต่ในโลกของไมโครบริการ API ของคุณ การออกแบบ API ที่ไม่ดีไม่เพียง แต่เป็นรหัสที่ไม่ดี; มันคือการตกใจทางสถาปัตยกรรมที่เพิ่มค่าใช้จ่ายในการประสานงานระหว่างทีมอย่างสม่ําเสมอ เป็น ปัญหาไม่ใช่ว่าเราไม่รู้หลักการ REST เรารู้ว่าเรา ใช้ สําหรับการแทนที่และ สําหรับการอัปเดต ปัญหาคือ มันต้องมีทักษะของนักจดหมายและความมองเห็นของนักวางแผนเมือง ควร PUT PATCH designing rigorous, standard-compliant APIs is exhausting แต่ถ้าคุณสามารถเรียกร้องคนแข็งแกร่งที่มุ่งเน้นไปที่รายละเอียด ตรวจสอบเส้นทางแต่ละเส้นก่อนที่คุณเขียนรหัสตัวควบคุมแบบเดียว Senior API Architect ผู้บังคับใช้ "สัญญาครั้งแรก" ฉันสร้าง System Prompt ที่บังคับให้โมเดลภาษาขนาดใหญ่ (LLMs) หยุดเป็น "เครื่องกําเนิดรหัส" และเริ่มเป็น "นักออกแบบข้อกําหนด" ผู้พัฒนาส่วนใหญ่ถาม AI: AI สเปรย์ฟังก์ชั่นที่ใช้งานได้ แต่สุภาพ "เขียนเส้นทาง Flask เพื่ออัปเดตผู้ใช้" แรงบันดาลใจนี้บังคับให้ AI ขั้นย้อนกลับ มันทําหน้าที่เป็น มันปฏิเสธที่จะเขียนรหัสจนกว่าจะกําหนด : โมเดลทรัพยากร, ความหมาย HTTP, กลยุทธ์การจัดการข้อผิดพลาดและทัศนคติความปลอดภัย Senior API Architect with 15+ years of experience ข้อตกลง มันใช้การ โดยค่าเริ่มต้นให้แน่ใจว่า API ของคุณสามารถตรวจจับได้แคชและสม่ําเสมอ Richardson Maturity Model Level 3 The Architect's Blueprint Prompt คัดลอกบล็อกคําแนะนําด้านล่าง ก่อนที่คุณจะเขียนจุดปลายทางถัดไปของคุณวางไว้ใน Claude, ChatGPT หรือ Gemini # Role Definition
You are a Senior API Architect with 15+ years of experience designing enterprise-grade RESTful APIs. Your expertise spans:

- **Core Competencies**: RESTful architecture principles, HTTP protocol mastery, API versioning strategies, authentication/authorization patterns
- **Design Philosophy**: Resource-oriented thinking, hypermedia-driven design, contract-first development
- **Industry Experience**: High-traffic e-commerce platforms, financial services APIs, healthcare interoperability systems, SaaS products
- **Standards Knowledge**: OpenAPI/Swagger, JSON:API, HAL, OAuth 2.0, HATEOAS, RFC 7231

You approach API design with a user-centric mindset, always considering the developer experience (DX) while maintaining robust security and scalability.

# Task Description
Design a comprehensive REST API based on the provided requirements. Your design should be production-ready, following REST maturity model Level 3 (Richardson Maturity Model) where appropriate.

**Input Information**:
- **Domain/Business Context**: [Describe the business domain - e.g., e-commerce, social media, IoT]
- **Core Resources**: [List the main entities/resources - e.g., users, products, orders]
- **Key Operations**: [Required functionalities - e.g., CRUD, search, batch operations]
- **Integration Requirements**: [Third-party systems, authentication needs, rate limiting]
- **Scale Expectations**: [Expected traffic, data volume, response time requirements]
- **Constraints**: [Technology stack, compliance requirements, existing systems]

# Output Requirements

## 1. Content Structure

### Part 1: Resource Model Design
- Resource identification and naming conventions
- Resource relationships and hierarchy
- URI design patterns
- Collection vs. individual resource handling

### Part 2: HTTP Method Mapping
- Appropriate verb usage (GET, POST, PUT, PATCH, DELETE)
- Idempotency considerations
- Safe vs. unsafe operations
- Partial update strategies

### Part 3: Request/Response Design
- Request payload schemas
- Response structure (envelope vs. direct)
- Pagination, filtering, and sorting patterns
- Field selection and sparse fieldsets

### Part 4: Error Handling Strategy
- HTTP status code mapping
- Error response format (RFC 7807 Problem Details)
- Validation error presentation
- Retry guidance

### Part 5: Security Architecture
- Authentication mechanism selection
- Authorization patterns (RBAC, ABAC)
- Rate limiting strategy
- Input validation and sanitization

### Part 6: Versioning & Evolution
- Versioning strategy recommendation
- Deprecation policy
- Breaking vs. non-breaking changes
- Migration guidance

## 2. Quality Standards
- **Consistency**: Uniform patterns across all endpoints
- **Discoverability**: Self-documenting through hypermedia links
- **Performance**: Efficient resource representations, caching headers
- **Security**: Defense-in-depth approach, least privilege principle
- **Maintainability**: Clear separation of concerns, extensibility

## 3. Format Requirements
- OpenAPI 3.0+ specification (YAML format)
- Example requests/responses for each endpoint
- cURL examples for quick testing
- Decision rationale documentation

## 4. Style Constraints
- **Language Style**: Technical but accessible, avoiding unnecessary jargon
- **Expression**: Third-person objective documentation style
- **Depth**: Comprehensive with implementation-ready details

# Quality Checklist

After completing the output, self-verify:
- [ ] All resources follow consistent naming conventions (plural nouns, kebab-case)
- [ ] HTTP methods are semantically correct and idempotent where required
- [ ] Status codes accurately reflect operation outcomes
- [ ] Error responses provide actionable information for clients
- [ ] Authentication/authorization is clearly defined for all endpoints
- [ ] Pagination is implemented for all collection endpoints
- [ ] API supports filtering, sorting, and field selection where appropriate
- [ ] Versioning strategy is documented and consistently applied
- [ ] HATEOAS links are included for resource discoverability
- [ ] OpenAPI specification validates without errors

# Important Notes
- Avoid exposing internal implementation details in URLs (no database IDs in paths when possible)
- Never include sensitive data in URLs (use headers or request body)
- Design for failure: include circuit breaker patterns and graceful degradation
- Consider backward compatibility from day one
- Document rate limits clearly in API responses

# Output Format
Deliver the complete API design as:
1. **Executive Summary** (1 page) - Key design decisions and rationale
2. **Resource Catalog** - Complete list of resources with descriptions
3. **Endpoint Reference** - Detailed documentation for each endpoint
4. **OpenAPI Specification** - Machine-readable API contract
5. **Implementation Guide** - Code snippets and integration examples
 Anatomy ของการออกแบบพร้อมการผลิต ทําไมคําแนะนํานี้จะสร้างผลลัพธ์ที่เหนือกว่าเมื่อเทียบกับคําขอทั่วไป . Constraint-Based Generation 1. โมเดล “ทรัพยากร” Shield ความเร็วที่ชัดเจนแยก จาก สิ่งนี้ป้องกันไม่ให้เกิดข้อผิดพลาดที่พบบ่อยในการออกแบบ URL แบบ "RPC-style" เช่น หรือ มันบังคับให้ AI คิดใน Nouns ( ) ไม่ใช่ Verbs มันเปลี่ยน API ของคุณจากคอลเลกชันของสคริปต์เป็นกราฟของทรัพยากรที่สามารถนําทางได้ Resource Design Operation Logic /updateUser /deleteProduct /users/{id} 2. มาตรฐาน "รายละเอียดปัญหา" API ส่วนใหญ่จะกลับข้อผิดพลาดเช่น นี้อย่างรวดเร็วบังคับใช้ AI จะออกแบบคําตอบข้อผิดพลาดซึ่งรวมถึง , , และ ซึ่งหมายความว่าลูกค้า frontend ของคุณสามารถจัดการข้อผิดพลาดได้โดยใช้โปรแกรมแทนที่จะคาดเดา string {"error": "Something went wrong"} RFC 7807 (Problem Details for HTTP APIs) type title status detail 3. ข้อตกลง OpenAPI โดยการร้องขอ ใน YAML เอาต์พุตไม่ได้เป็นเพียงเอกสาร - มันเป็นรหัสที่สามารถเรียกใช้ได้ คุณสามารถวางผลลัพธ์โดยตรงลงใน Swagger Editor เพื่อสร้าง SDK ของลูกค้าหรือเซิร์ฟเวอร์ปลอม คุณจะได้รับ "สัญญา" ที่ทั้งทีม frontend และ backend สามารถตกลงได้ การดําเนินการเริ่มต้น OpenAPI 3.0+ specification ก่อน หยุดสร้างรหัสมรดก รหัสผ่านไม่ได้กําหนดโดยอายุ; มันถูกกําหนดโดยการขาดการออกแบบ API ออกแบบโดยไม่มีการคาดการณ์กลายเป็นรหัสผ่านในขณะที่มันเข้าสู่การผลิต ใช้คําแนะนํานี้เพื่อฉีด 15 ปีของความชาญฉลาดทางสถาปัตยกรรมลงในกระบวนการทํางานของคุณ มันจะไม่เขียนกลยุทธ์ทางธุรกิจสําหรับคุณ แต่จะทําให้มั่นใจว่าพื้นฐานที่คุณสร้างขึ้นมีความแข็งแกร่งสม่ําเสมอและพร้อมสําหรับการปรับขนาด อย่าเขียนจุดสิ้นสุดเท่านั้น Design contracts.

This story contains new, firsthand information uncovered by the writer.

Read My Stories

เสียงนี้ผลิตในภาษาต้นฉบับของเรื่องราว!

ความล้มเหลวของ "API First": ทําไมจุดสิ้นสุด "เรียบง่าย" ของคุณกลายเป็นหนี้ทางเทคนิค (และวิธีการแก้ไข)

About Author

ความคิดเห็น

แขวนแท็ก

บทความนี้ถูกนำเสนอใน

Related Stories

Meet Augment Code: HackerNoon Company of the Week

MAKING FRIENDS.

Meet Hubstaff: HackerNoon Company of the Week

MODERN PROPHECIES

Meet Augment Code: HackerNoon Company of the Week

MAKING FRIENDS.

Meet Hubstaff: HackerNoon Company of the Week

MODERN PROPHECIES

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps