Počelo je kao bezopasna Slack poruka u 4:30 u petak. "Hej, frontend treba brzu krajnju tačku za prikaz korisničkih preferencija. Samo vratite JSON blob iz DB-a. trebalo bi da traje 10 minuta." "Hej, frontend treba brzu krajnju tačku za prikaz korisničkih preferencija. Samo vratite JSON blob iz DB-a. trebalo bi da traje 10 minuta." Šest meseci kasnije, ta "10-minutna krajnja tačka" je mutovala u monolit. Vraća 4 MB podataka, miješa camelCase i snake_case, nedostaje paginiranje i prekida svaki put kada dodirnete shemu baze podataka. Niste dizajnirali API; samo ste izložili bazu podataka preko HTTP-a i nadali se najboljem. /v1/user/stuff This is the silent killer of modern software scalability. Mi tretiramo dizajn API-ja kao razmišljanje – vodeni zadatak da se podaci iz A u B. Ali u svetu mikroslužbi, vaš API Loš dizajn API-ja nije samo ružan kod; to je arhitektonska entropija koja eksponencijalno povećava troškove koordinacije između timova. je Problem nije u tome što ne znamo načela REST-a. Koristite Za zamjenu i za ažuriranje. problem je u tome To zahtijeva disciplinu bibliotekarca i predviđanje gradskog planera. treba PUT PATCH designing rigorous, standard-compliant APIs is exhausting Ali šta ako možete pozvati tvrdoglavog, detaljno orijentiranog da pregledate svaki put pre nego što napišete jednu liniju koda kontrolera? Senior API Architect Izvršitelj „prvog ugovora“ Izradio sam System Prompt koji prisiljava velike jezične modele (LLM) da prestanu biti "generatori koda" i počnu da budu "projektori specifikacija". Većina programera pita AI: AI ispušta funkcionalnu, ali naivnu funkciju. "Napišite Flask put za ažuriranje korisnika." Ovaj prompt prisiljava AI da se povuče. djeluje kao Ona odbija da napiše kod dok ne definira : model resursa, HTTP semantika, strategija rješavanja grešaka i sigurnosni stav. Senior API Architect with 15+ years of experience Ugovor Ona implementira podrazumevano, osiguravajući da je vaš API otkrivljiv, cacheable i ujednačen. Richardson Maturity Model Level 3 The Architect's Blueprint Prompt (Arhitektova promptna promptna promptna Prije nego što napišete sledeću krajnju tačku, prilepite je u Claude, ChatGPT ili 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 Anatomija dizajna spremnog za proizvodnju Zašto ovaj poziv generira superiorne rezultate u usporedbi sa generičkim zahtjevom? . Constraint-Based Generation 1. „Model resursa“ Štit Ubrzanje jasno razdvaja od To sprečava uobičajenu grešku dizajniranja URL-ova u stilu "RPC" kao što su ili To prisiljava AI da razmišlja u Nouns ( ), a ne Verbs. pretvara vaš API iz zbirke skripta u navigacijski graf resursa. Resource Design Operation Logic /updateUser /deleteProduct /users/{id} Standard „Problem Detalji“ Većina API-ja vraća greške kao što su Ova brza primjena AI će dizajnirati odgovore na greške koji uključuju U pitanju je U pitanju je i To znači da vaši frontend klijenti mogu programski upravljati greškama umjesto nagađanja niza. {"error": "Something went wrong"} RFC 7807 (Problem Details for HTTP APIs) type title status detail OpenAPI ugovor Zahtijevajući da u YAML, izlaz nije samo dokumentacija – to je izvršivi kod. Možete umetnuti rezultat direktno u Swagger Editor da biste generisali SDK klijenta ili mock servere. Dobijate "Ugovor" na koji se i frontend i backend timovi mogu složiti Počinje implementacija. OpenAPI 3.0+ specification Prije Zaustavite izgradnju Legacy Code Legacy kod nije definisan dobom; to je definisano nedostatkom dizajna. API dizajniran bez predviđanja postaje legacy kod u trenutku kada udari u proizvodnju. Upotrijebite ovaj uput za ubrizgavanje 15 godina arhitektonske mudrosti u vaš tok posla.To neće napisati poslovnu logiku za vas, ali će osigurati da je temelj na kojem gradite čvrst, dosljedan i spreman za razmjenu. Ne pišite samo krajnje tačke. Design contracts.
