"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; function _createMdxContent(props) { const _components = { a: "a", blockquote: "blockquote", code: "code", h1: "h1", h2: "h2", h3: "h3", h4: "h4", li: "li", ol: "ol", p: "p", pre: "pre", span: "span", strong: "strong", table: "table", tbody: "tbody", td: "td", th: "th", thead: "thead", tr: "tr", ul: "ul", ..._provideComponents(), ...props.components }; return _jsxs(_Fragment, { children: [_jsx(_components.h1, { id: "api-design--building-restful-interfaces-that-scale", children: "API Design: Building RESTful Interfaces That Scale" }), "\n", _jsx(_components.p, { children: "API design is not an afterthought. It is not something you figure out while writing your first handler function. It is a foundational skill that separates backend engineers who build maintainable systems from those who create technical debt." }), "\n", _jsx(_components.p, { children: "When you design APIs well, your interfaces become intuitive, your documentation writes itself, and your consumers integrate faster with fewer support tickets. When you design APIs poorly, you create confusion, inconsistency, and a constant stream of \"why doesn't this work?\" messages from frontend engineers and third-party developers." }), "\n", _jsx(_components.p, { children: "We will cover REST API design from first principles: historical context, core architectural constraints, URL structure, HTTP method semantics, idempotency, pagination, filtering, sorting, custom actions, and practical patterns you can apply immediately. We will walk through a complete project management platform example, designing every endpoint for organizations, projects, and tasks." }), "\n", _jsx(_components.p, { children: "If you are new to API design, this will give you a solid foundation. If you are experienced, this will help you refine your approach and catch edge cases you might have missed." }), "\n", _jsx(_components.h2, { id: "topics", children: "Topics" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#the-problem-with-api-design", children: "The Problem with API Design" }) }), "\n", _jsxs(_components.li, { children: [_jsx(_components.a, { href: "#historical-context-where-rest-came-from", children: "Historical Context: Where REST Came From" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#the-birth-of-the-web", children: "The Birth of the Web" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#the-scalability-crisis", children: "The Scalability Crisis" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#the-six-rest-constraints", children: "The Six REST Constraints" }) }), "\n"] }), "\n"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.a, { href: "#why-is-it-called-rest", children: "Why Is It Called REST" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#representational", children: "Representational" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#state", children: "State" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#transfer", children: "Transfer" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#putting-it-all-together", children: "Putting It All Together" }) }), "\n"] }), "\n"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.a, { href: "#url-structure-for-apis", children: "URL Structure for APIs" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#anatomy-of-a-url", children: "Anatomy of a URL" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#api-url-structure", children: "API URL Structure" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#resource-naming-rules", children: "Resource Naming Rules" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#slug-conversion", children: "Slug Conversion" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#hierarchical-paths", children: "Hierarchical Paths" }) }), "\n"] }), "\n"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.a, { href: "#idempotency-and-http-methods", children: "Idempotency and HTTP Methods" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#what-is-idempotency", children: "What Is Idempotency" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#idempotency-by-http-method", children: "Idempotency by HTTP Method" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#patch-idempotency-it-depends", children: "PATCH Idempotency: It Depends" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#post-for-custom-actions", children: "POST for Custom Actions" }) }), "\n"] }), "\n"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.a, { href: "#api-design-workflow-from-wireframes-to-endpoints", children: "API Design Workflow: From Wireframes to Endpoints" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#step-1-start-with-uiwireframes", children: "Step 1: Start with UI/Wireframes" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#step-2-identify-resources-nouns", children: "Step 2: Identify Resources (Nouns)" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#step-3-design-database-schema", children: "Step 3: Design Database Schema" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#step-4-identify-actions-crud--custom", children: "Step 4: Identify Actions (CRUD + Custom)" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#step-5-design-the-interface", children: "Step 5: Design the Interface" }) }), "\n"] }), "\n"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.a, { href: "#designing-organization-apis", children: "Designing Organization APIs" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#list-organizations-get", children: "List Organizations (GET)" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#create-organization-post", children: "Create Organization (POST)" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#get-single-organization-get", children: "Get Single Organization (GET)" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#update-organization-patch", children: "Update Organization (PATCH)" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#delete-organization-delete", children: "Delete Organization (DELETE)" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#custom-action-archive-organization", children: "Custom Action: Archive Organization" }) }), "\n"] }), "\n"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.a, { href: "#pagination-sorting-and-filtering", children: "Pagination, Sorting, and Filtering" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#why-pagination-exists", children: "Why Pagination Exists" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#pagination-response-structure", children: "Pagination Response Structure" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#pagination-in-practice", children: "Pagination in Practice" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#sorting-in-list-apis", children: "Sorting in List APIs" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#filtering-in-list-apis", children: "Filtering in List APIs" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#combining-parameters", children: "Combining Parameters" }) }), "\n"] }), "\n"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.a, { href: "#designing-project-apis", children: "Designing Project APIs" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#create-project-post", children: "Create Project (POST)" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#list-projects-get", children: "List Projects (GET)" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#get-single-project-get", children: "Get Single Project (GET)" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#update-project-patch", children: "Update Project (PATCH)" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#delete-project-delete", children: "Delete Project (DELETE)" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#custom-action-clone-project", children: "Custom Action: Clone Project" }) }), "\n"] }), "\n"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.a, { href: "#consistency-across-resources", children: "Consistency Across Resources" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#json-field-naming", children: "JSON Field Naming" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#payload-structure", children: "Payload Structure" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#route-patterns", children: "Route Patterns" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#query-parameter-names", children: "Query Parameter Names" }) }), "\n"] }), "\n"] }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#status-code-reference", children: "Status Code Reference" }) }), "\n", _jsxs(_components.li, { children: [_jsx(_components.a, { href: "#best-practices-for-api-design", children: "Best Practices for API Design" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#provide-interactive-documentation", children: "Provide Interactive Documentation" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#make-apis-intuitive-and-consistent", children: "Make APIs Intuitive and Consistent" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#provide-sane-defaults", children: "Provide Sane Defaults" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#avoid-abbreviations", children: "Avoid Abbreviations" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#design-before-you-code", children: "Design Before You Code" }) }), "\n"] }), "\n"] }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#common-pitfalls-and-how-to-avoid-them", children: "Common Pitfalls and How to Avoid Them" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "#conclusion", children: "Conclusion" }) }), "\n"] }), "\n", _jsx(_components.h2, { id: "the-problem-with-api-design", children: "The Problem with API Design" }), "\n", _jsx(_components.p, { children: "REST has been the dominant API architectural style for over two decades. Thousands of engineers have built APIs using its principles. Countless articles, books, and talks have explained its concepts. Yet new developers still ask the same questions, and experienced engineers still debate the same decisions:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["Should resource paths be plural or singular? ", _jsx(_components.code, { children: "/users" }), " or ", _jsx(_components.code, { children: "/user" }), "?"] }), "\n", _jsxs(_components.li, { children: ["When updating a resource, should I use ", _jsx(_components.code, { children: "PUT" }), " or ", _jsx(_components.code, { children: "PATCH" }), "? What is the actual difference?"] }), "\n", _jsx(_components.li, { children: "What HTTP method do I use for a custom action that isn't create, read, update, or delete?" }), "\n", _jsxs(_components.li, { children: ["Which status code fits this scenario? ", _jsx(_components.code, { children: "200" }), ", ", _jsx(_components.code, { children: "201" }), ", ", _jsx(_components.code, { children: "204" }), ", ", _jsx(_components.code, { children: "400" }), ", ", _jsx(_components.code, { children: "404" }), ", ", _jsx(_components.code, { children: "422" }), "?"] }), "\n", _jsxs(_components.li, { children: ["Should I return the updated resource after a ", _jsx(_components.code, { children: "PATCH" }), ", or just a success message?"] }), "\n", _jsx(_components.li, { children: "How do I handle pagination? Query parameters or request body?" }), "\n", _jsx(_components.li, { children: "What about filtering and sorting? How do I design those query parameters?" }), "\n", _jsx(_components.li, { children: "Should I version my APIs? If so, how? In the URL, headers, or content negotiation?" }), "\n"] }), "\n", _jsx(_components.p, { children: "These questions persist not because REST is unclear, but because the web has evolved dramatically since REST was formalized. When Roy Fielding described REST in his 2000 dissertation, most web applications were Multi-Page Applications (MPAs). Pages were rendered on the server, links navigated to new pages, and forms submitted to server endpoints. The client was relatively thin." }), "\n", _jsx(_components.p, { children: "Today, Single Page Applications (SPAs) dominate. The browser downloads a JavaScript bundle on first load, and all subsequent navigation and data fetching happens client-side via API calls. The client is thick, stateful, and often maintains its own cache. Mobile apps, server-to-server integrations, and IoT devices add even more variety to API consumers." }), "\n", _jsx(_components.p, { children: "The context changed, but the core principles of REST remain valid. The goal of this guide is not to invent new standards. It is to extract clear, actionable, practical guidelines from existing REST specifications and real-world experience so you can:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Design predictable, intuitive routes that consumers can guess correctly" }), "\n", _jsx(_components.li, { children: "Structure consistent request and response payloads that are easy to parse" }), "\n", _jsx(_components.li, { children: "Return appropriate HTTP status codes that convey meaning without ambiguity" }), "\n", _jsx(_components.li, { children: "Document behavior clearly so consumers do not need to read your source code" }), "\n", _jsx(_components.li, { children: "Build APIs that scale in complexity without becoming unmaintainable" }), "\n"] }), "\n", _jsx(_components.p, { children: "When you follow established patterns, you stop debating style and start shipping features. You reduce onboarding time for new team members. You minimize support burden from API consumers. You create a foundation that can evolve without breaking existing integrations." }), "\n", _jsx(_components.h2, { id: "historical-context-where-rest-came-from", children: "Historical Context: Where REST Came From" }), "\n", _jsx(_components.p, { children: "Understanding where REST came from helps you apply it correctly. It is not arbitrary. Each constraint solves a specific problem." }), "\n", _jsx(_components.h3, { id: "the-birth-of-the-web", children: "The Birth of the Web" }), "\n", _jsx(_components.p, { children: "In 1990, Tim Berners-Lee, a British computer scientist working at CERN, started a project called the World Wide Web. His motivation was simple: enable researchers around the world to share knowledge and documents easily." }), "\n", _jsx(_components.p, { children: "Within about a year, Berners-Lee invented the foundational technologies that still power the web today:" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "URI (Uniform Resource Identifier)" }), " - A string that identifies a resource. Examples: ", _jsx(_components.code, { children: "https://example.com/users/123" }), ", ", _jsx(_components.code, { children: "mailto:alice@example.com" }), ". URIs provide a universal addressing scheme."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "HTTP (Hypertext Transfer Protocol)" }), " - The application-layer protocol for client-server communication. HTTP defines methods (", _jsx(_components.code, { children: "GET" }), ", ", _jsx(_components.code, { children: "POST" }), ", etc.), status codes (", _jsx(_components.code, { children: "200" }), ", ", _jsx(_components.code, { children: "404" }), ", etc.), headers, and message formats."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "HTML (Hypertext Markup Language)" }), " - The markup language for structuring web pages. HTML introduced hyperlinks, enabling navigation between resources."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "The first web server" }), " - Software that listens for HTTP requests and returns responses. Berners-Lee's server ran on a NeXT computer."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "The first web browser" }), " - Software that renders HTML and allows users to navigate the web. The first browser was also an editor."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "The first WYSIWYG HTML editor" }), " - Built into the browser, allowing users to create and edit web content visually."] }), "\n"] }), "\n"] }), "\n", _jsx(_components.p, { children: "We still use advanced versions of all these technologies. HTTP has evolved through versions 1.1, 2, and 3. HTML has added semantic elements, APIs, and multimedia support. Web servers and browsers are vastly more sophisticated. But the core concepts remain." }), "\n", _jsx(_components.h3, { id: "the-scalability-crisis", children: "The Scalability Crisis" }), "\n", _jsx(_components.p, { children: "The web grew faster than anyone anticipated. Within a few years, thousands of users were connecting daily. Berners-Lee had not designed the original architecture for exponential growth. The system began to show strain." }), "\n", _jsx(_components.p, { children: "To address scalability, new techniques, standards, and components had to be introduced. Around 1993, Roy Fielding, a graduate student and co-founder of the Apache HTTP Server project, became concerned about the web's scalability problem. He proposed a set of architectural constraints that could help the web scale to accommodate millions of users." }), "\n", _jsx(_components.h3, { id: "the-six-rest-constraints", children: "The Six REST Constraints" }), "\n", _jsx(_components.p, { children: "Fielding's constraints form the foundation of REST. Each constraint addresses a specific architectural concern." }), "\n", _jsx(_components.h4, { id: "1-client-server", children: "1. Client-Server" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "hljs language-mermaid", "data-mermaid": "true", children: "flowchart LR\n Client[Client: UI/UX, State Management] <--> HTTP[HTTP Protocol] <--> Server[Server: Data Storage, Business Logic]\n" }) }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "What it means:" }), " Separation of concerns between client and server. The client handles user interface, user experience, and client-side state. The server handles data storage, business logic, and authentication."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Why it matters:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Clients and servers can evolve independently. The server can change its database schema without affecting clients, as long as the API contract remains stable." }), "\n", _jsx(_components.li, { children: "Different clients (web, mobile, CLI) can consume the same server API." }), "\n", _jsx(_components.li, { children: "Servers can scale horizontally without requiring changes to clients." }), "\n"] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Practical implication:" }), " Do not embed business logic in your frontend. Do not expose your database schema directly to clients. Use an API layer as a contract."] }), "\n", _jsx(_components.h4, { id: "2-uniform-interface", children: "2. Uniform Interface" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "What it means:" }), " A standardized way for components to communicate. The uniform interface has four sub-constraints:"] }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Sub-constraint" }), _jsx(_components.th, { children: "Description" }), _jsx(_components.th, { children: "Example" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Resource identification" }), _jsx(_components.td, { children: "Resources are identified by URIs" }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "/api/v1/users/123" }), " identifies a specific user"] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Resource manipulation through representations" }), _jsx(_components.td, { children: "Clients modify resources by sending representations (JSON, XML)" }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "PATCH /users/123" }), " with ", _jsx(_components.code, { children: "{\"name\": \"Alice\"}" }), " updates the user's name"] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Self-descriptive messages" }), _jsx(_components.td, { children: "Each message contains enough information to process it" }), _jsx(_components.td, { children: "HTTP method, headers, and body together describe the request" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "HATEOAS (Hypermedia as the Engine of Application State)" }), _jsx(_components.td, { children: "Responses include links to related actions" }), _jsxs(_components.td, { children: ["A user response includes ", _jsx(_components.code, { children: "\"links\": {\"projects\": \"/users/123/projects\"}" })] })] })] })] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Why it matters:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Consistency across services. Engineers can work on different parts of the system without learning new interaction patterns." }), "\n", _jsx(_components.li, { children: "Discoverability. Clients can navigate the API by following links." }), "\n", _jsx(_components.li, { children: "Interoperability. Different implementations can communicate because they follow the same interface." }), "\n"] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Practical implication:" }), " Use standard HTTP methods consistently. Return hypermedia links when it adds value. Document your API contract clearly."] }), "\n", _jsx(_components.h4, { id: "3-layered-system", children: "3. Layered System" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "hljs language-mermaid", "data-mermaid": "true", children: "flowchart TB\n Client --> LB[Load Balancer]\n LB --> Proxy[API Gateway/Proxy]\n Proxy --> App[Application Server]\n App --> Cache[Cache Layer]\n App --> DB[(Database)]\n" }) }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "What it means:" }), " The architecture is composed of hierarchical layers. Each layer can only interact with the immediate layer below it. Layers can include load balancers, proxies, caches, and application servers."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Why it matters:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Scalability. You can add layers (like a cache or CDN) without changing core logic." }), "\n", _jsx(_components.li, { children: "Security. Proxies can handle authentication, rate limiting, and request validation before traffic reaches your application." }), "\n", _jsx(_components.li, { children: "Maintainability. Layers can be replaced or upgraded independently." }), "\n"] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Practical implication:" }), " Design your API so it can sit behind a proxy or load balancer. Do not assume direct client-to-server communication."] }), "\n", _jsx(_components.h4, { id: "4-cache", children: "4. Cache" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "What it means:" }), " Responses must be explicitly labeled as cacheable or non-cacheable. The server controls caching behavior via HTTP headers like ", _jsx(_components.code, { children: "Cache-Control" }), ", ", _jsx(_components.code, { children: "ETag" }), ", and ", _jsx(_components.code, { children: "Last-Modified" }), "."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Why it matters:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Performance. Cached responses reduce server load and improve response times." }), "\n", _jsx(_components.li, { children: "Efficiency. Clients can avoid re-fetching unchanged resources." }), "\n", _jsx(_components.li, { children: "Scalability. Caching layers can serve repeated requests without hitting your application." }), "\n"] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Practical implication:" }), " Set appropriate cache headers for each endpoint. ", _jsx(_components.code, { children: "GET" }), " requests for static data can be cached aggressively. ", _jsx(_components.code, { children: "POST" }), ", ", _jsx(_components.code, { children: "PUT" }), ", ", _jsx(_components.code, { children: "PATCH" }), ", and ", _jsx(_components.code, { children: "DELETE" }), " responses should generally not be cached."] }), "\n", _jsx(_components.h4, { id: "5-stateless", children: "5. Stateless" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "What it means:" }), " Each request from client to server must contain all information necessary to understand and process the request. The server does not store client context between requests."] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "hljs language-mermaid", "data-mermaid": "true", children: "sequenceDiagram\n participant C as Client\n participant S as Server\n \n C->>S: GET /users/123
Authorization: Bearer abc123\n S-->>C: 200 OK + user data\n \n C->>S: PATCH /users/123
Authorization: Bearer abc123
{\"name\": \"Alice\"}\n S-->>C: 200 OK + updated user\n" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Why it matters:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Reliability. Any server instance can handle any request. No session affinity required." }), "\n", _jsx(_components.li, { children: "Scalability. You can add or remove server instances without disrupting clients." }), "\n", _jsx(_components.li, { children: "Visibility. Each request is self-contained, making logging and debugging easier." }), "\n"] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Practical implication:" }), " Do not store session state on the server. Use tokens (JWT, opaque tokens) that contain all necessary context. Include authentication credentials with each request."] }), "\n", _jsx(_components.h4, { id: "6-code-on-demand-optional", children: "6. Code on Demand (Optional)" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "What it means:" }), " Servers can temporarily extend client functionality by transferring executable code, such as JavaScript."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Why it matters:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Flexibility. Clients can receive new behavior without updates." }), "\n", _jsx(_components.li, { children: "Efficiency. Common logic can be shared via code downloads." }), "\n"] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Practical implication:" }), " This constraint is rarely used in API design. Most REST APIs do not transfer executable code. It remains optional for specialized use cases."] }), "\n", _jsx(_components.h3, { id: "the-rest-dissertation", children: "The REST Dissertation" }), "\n", _jsxs(_components.p, { children: ["In 2000, after the web's scalability crisis was addressed, Roy Fielding named and described the web's architectural style in his PhD dissertation: \"Architectural Styles and the Design of Network-based Software Architectures.\" He called it ", _jsx(_components.strong, { children: "REST: Representational State Transfer" }), "."] }), "\n", _jsx(_components.p, { children: "Fielding's dissertation is a dense, academic document. Reading it provides deep context for why REST constraints exist. If you are a backend engineer, it is worth reading at least the sections on REST. Search for \"Roy Fielding REST dissertation\" to find the original document." }), "\n", _jsx(_components.p, { children: "You do not need to memorize every detail. But understanding the motivation behind REST helps you apply its principles correctly, especially when facing edge cases or trade-offs." }), "\n", _jsx(_components.h2, { id: "why-is-it-called-rest", children: "Why Is It Called REST" }), "\n", _jsx(_components.p, { children: "The name \"Representational State Transfer\" is descriptive. Breaking it down clarifies what REST actually means." }), "\n", _jsx(_components.h3, { id: "representational", children: "Representational" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Resources" }), " on the web are abstract concepts: a user, a book, a shopping cart. They do not have a physical form. To interact with them, we use ", _jsx(_components.strong, { children: "representations" }), ": specific formats that encode the resource's state."] }), "\n", _jsx(_components.p, { children: "Common representation formats:" }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Format" }), _jsx(_components.th, { children: "Use Case" }), _jsx(_components.th, { children: "Example" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: "JSON" }), _jsx(_components.td, { children: "API client communication" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "{\"id\": 123, \"name\": \"Alice\"}" }) })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "HTML" }), _jsx(_components.td, { children: "Browser rendering" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "

Alice

" }) })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "XML" }), _jsx(_components.td, { children: "Legacy integrations, SOAP" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "123Alice" }) })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Protocol Buffers" }), _jsx(_components.td, { children: "High-performance internal APIs" }), _jsx(_components.td, { children: "Binary format, schema-defined" })] })] })] }), "\n", _jsx(_components.p, { children: "The same resource can have multiple representations. A user resource might be:" }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-comment", children: "// JSON representation for API client" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"id\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"usr_123\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Alice\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"email\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"alice@example.com\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"createdAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-01-15T10:30:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"roles\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "[" }), _jsx(_components.span, { className: "hljs-string", children: "\"admin\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"editor\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "]" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-html", children: [_jsx(_components.span, { className: "hljs-comment", children: "" }), "\n", _jsxs(_components.span, { className: "hljs-meta", children: [""] }), "\n", _jsxs(_components.span, { className: "hljs-tag", children: ["<", _jsx(_components.span, { className: "hljs-name", children: "html" }), ">"] }), "\n", _jsxs(_components.span, { className: "hljs-tag", children: ["<", _jsx(_components.span, { className: "hljs-name", children: "body" }), ">"] }), "\n ", _jsxs(_components.span, { className: "hljs-tag", children: ["<", _jsx(_components.span, { className: "hljs-name", children: "div" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "class" }), "=", _jsx(_components.span, { className: "hljs-string", children: "\"user-profile\"" }), ">"] }), "\n ", _jsxs(_components.span, { className: "hljs-tag", children: ["<", _jsx(_components.span, { className: "hljs-name", children: "h1" }), ">"] }), "Alice", _jsxs(_components.span, { className: "hljs-tag", children: [""] }), "\n ", _jsxs(_components.span, { className: "hljs-tag", children: ["<", _jsx(_components.span, { className: "hljs-name", children: "p" }), ">"] }), "alice@example.com", _jsxs(_components.span, { className: "hljs-tag", children: [""] }), "\n ", _jsxs(_components.span, { className: "hljs-tag", children: ["<", _jsx(_components.span, { className: "hljs-name", children: "span" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "class" }), "=", _jsx(_components.span, { className: "hljs-string", children: "\"badge admin\"" }), ">"] }), "Admin", _jsxs(_components.span, { className: "hljs-tag", children: [""] }), "\n ", _jsxs(_components.span, { className: "hljs-tag", children: ["<", _jsx(_components.span, { className: "hljs-name", children: "span" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "class" }), "=", _jsx(_components.span, { className: "hljs-string", children: "\"badge editor\"" }), ">"] }), "Editor", _jsxs(_components.span, { className: "hljs-tag", children: [""] }), "\n ", _jsxs(_components.span, { className: "hljs-tag", children: ["<", _jsx(_components.span, { className: "hljs-name", children: "small" }), ">"] }), "Member since January 2025", _jsxs(_components.span, { className: "hljs-tag", children: [""] }), "\n ", _jsxs(_components.span, { className: "hljs-tag", children: [""] }), "\n", _jsxs(_components.span, { className: "hljs-tag", children: [""] }), "\n", _jsxs(_components.span, { className: "hljs-tag", children: [""] }), "\n"] }) }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Key insight:" }), " The representation is not the resource. The resource is the abstract concept; the representation is how we encode it for transmission."] }), "\n", _jsx(_components.h3, { id: "state", children: "State" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "State" }), " refers to the current attributes of a resource at a specific point in time."] }), "\n", _jsx(_components.p, { children: "Example: An e-commerce shopping cart resource." }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"cartId\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"cart_789\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"userId\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"usr_123\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"items\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "[" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"productId\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"prod_101\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Wireless Headphones\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"quantity\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "2" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"price\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "79.99" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"currency\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"USD\"" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"productId\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"prod_202\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Phone Case\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"quantity\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "1" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"price\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "19.99" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"currency\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"USD\"" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "]" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"subtotal\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "179.97" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"tax\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "14.40" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"total\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "194.37" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"currency\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"USD\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"updatedAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T14:22:00Z\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsxs(_components.p, { children: ["This JSON document represents the state of the shopping cart at the moment it was fetched. If the user adds another item, the state changes. The next ", _jsx(_components.code, { children: "GET" }), " request will return a different representation."] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Key insight:" }), " State is transferable. The client and server exchange representations that encode the resource's current state."] }), "\n", _jsx(_components.h3, { id: "transfer", children: "Transfer" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Transfer" }), " describes the movement of resource representations between client and server via HTTP."] }), "\n", _jsx(_components.p, { children: "HTTP methods define the semantics of transfer:" }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Method" }), _jsx(_components.th, { children: "Semantics" }), _jsx(_components.th, { children: "Idempotent" }), _jsx(_components.th, { children: "Safe" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "GET" }) }), _jsx(_components.td, { children: "Retrieve a representation" }), _jsx(_components.td, { children: "Yes" }), _jsx(_components.td, { children: "Yes" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "HEAD" }) }), _jsx(_components.td, { children: "Retrieve headers only" }), _jsx(_components.td, { children: "Yes" }), _jsx(_components.td, { children: "Yes" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "POST" }) }), _jsx(_components.td, { children: "Create a new resource or execute an action" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: "No" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "PUT" }) }), _jsx(_components.td, { children: "Replace a resource entirely" }), _jsx(_components.td, { children: "Yes" }), _jsx(_components.td, { children: "No" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "PATCH" }) }), _jsx(_components.td, { children: "Partially update a resource" }), _jsx(_components.td, { children: "Depends" }), _jsx(_components.td, { children: "No" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "DELETE" }) }), _jsx(_components.td, { children: "Remove a resource" }), _jsx(_components.td, { children: "Yes" }), _jsx(_components.td, { children: "No" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "OPTIONS" }) }), _jsx(_components.td, { children: "Describe communication options" }), _jsx(_components.td, { children: "Yes" }), _jsx(_components.td, { children: "Yes" })] })] })] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Key insight:" }), " Transfer is standardized. HTTP provides a common vocabulary for client-server communication."] }), "\n", _jsx(_components.h3, { id: "putting-it-all-together", children: "Putting It All Together" }), "\n", _jsx(_components.p, { children: "REST describes an architectural style where:" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Resources are identified by URIs" }), " - Every resource has a unique address."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Resources have multiple representation formats" }), " - JSON for APIs, HTML for browsers, etc."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Resource state transfers between client and server" }), " - Via HTTP methods and messages."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Communication follows a uniform interface" }), " - Standard methods, status codes, headers."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "The system is stateless" }), " - Each request is self-contained."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "The system is layered" }), " - Proxies, caches, and gateways can be added transparently."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Responses are cacheable when appropriate" }), " - Improving performance and scalability."] }), "\n"] }), "\n", _jsx(_components.p, { children: "When you design a REST API, you are applying these principles to create an interface that is predictable, scalable, and maintainable." }), "\n", _jsx(_components.h2, { id: "url-structure-for-apis", children: "URL Structure for APIs" }), "\n", _jsx(_components.p, { children: "URLs are the primary way clients identify and interact with your resources. Getting URL structure right is critical for API usability." }), "\n", _jsx(_components.h3, { id: "anatomy-of-a-url", children: "Anatomy of a URL" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: "https://sriniously.xyz/blog/zist?q=something#header\n│ │ │ │ │\n│ │ │ │ └─ Fragment: Client-side navigation anchor\n│ │ │ └─ Query string: Key-value parameters for filtering, pagination, etc.\n│ │ └─ Path: Hierarchical resource identifier\n│ └─ Authority: Domain and optional port\n└─ Scheme: Protocol (http or https)\n" }) }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Component" }), _jsx(_components.th, { children: "Description" }), _jsx(_components.th, { children: "Example" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Scheme" }), _jsx(_components.td, { children: "Protocol used for communication" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "https" }) })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Authority" }), _jsx(_components.td, { children: "Domain name and optional port" }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "sriniously.xyz" }), ", ", _jsx(_components.code, { children: "api.example.com:8080" })] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Path" }), _jsx(_components.td, { children: "Hierarchical resource identifier" }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "/blog/zist" }), ", ", _jsx(_components.code, { children: "/api/v1/users/123" })] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Query string" }), _jsx(_components.td, { children: "Key-value parameters for filtering, sorting, pagination" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "?q=something&limit=20" }) })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Fragment" }), _jsx(_components.td, { children: "Client-side anchor for in-page navigation" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "#header" }) })] })] })] }), "\n", _jsx(_components.h3, { id: "api-url-structure", children: "API URL Structure" }), "\n", _jsx(_components.p, { children: "Production APIs typically follow a consistent structure:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: "https://api.example.com/v1/organizations\n│ │ │ │ └─ Resource: Plural, lowercase, hyphenated\n│ │ │ └─ Version: v1, v2, etc.\n│ │ └─ Subdomain: Dedicated API domain\n│ └─ Domain: Your organization's domain\n└─ Scheme: Always https in production\n" }) }), "\n", _jsx(_components.h4, { id: "why-a-dedicated-api-subdomain", children: "Why a Dedicated API Subdomain?" }), "\n", _jsxs(_components.p, { children: ["Using ", _jsx(_components.code, { children: "api.example.com" }), " instead of ", _jsx(_components.code, { children: "example.com/api" }), " provides several benefits:"] }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Clear separation:" }), " API traffic is distinct from web traffic."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Independent scaling:" }), " You can scale API servers separately from web servers."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Simplified CORS:" }), " Browsers enforce same-origin policy; a dedicated subdomain makes CORS configuration explicit."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Monitoring and logging:" }), " API requests can be tracked separately."] }), "\n"] }), "\n", _jsx(_components.h4, { id: "why-version-in-the-url", children: "Why Version in the URL?" }), "\n", _jsxs(_components.p, { children: ["Including the version in the path (", _jsx(_components.code, { children: "/v1/" }), ") is the most practical approach for most APIs:"] }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Explicit:" }), " Clients know exactly which version they are using."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Cacheable:" }), " Different versions have different URLs, so caches do not mix them."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Simple:" }), " No need for complex content negotiation or header parsing."] }), "\n"] }), "\n", _jsx(_components.p, { children: "Alternative versioning strategies exist (headers, query parameters, content negotiation), but URL versioning is the most straightforward and widely adopted." }), "\n", _jsx(_components.h3, { id: "resource-naming-rules", children: "Resource Naming Rules" }), "\n", _jsx(_components.h4, { id: "rule-1-always-use-plural-nouns", children: "Rule 1: Always Use Plural Nouns" }), "\n", _jsx(_components.p, { children: "Use plural nouns for resource names, even when referring to a single resource:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: "GET /api/v1/books # List all books\nGET /api/v1/books/123 # Get book with ID 123\nPOST /api/v1/books # Create a new book\nPATCH /api/v1/books/123 # Update book with ID 123\nDELETE /api/v1/books/123 # Delete book with ID 123\n\nGET /api/v1/book # Inconsistent: singular\nGET /api/v1/book/123 # Inconsistent: singular\n" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Why plural?" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["Consistency: The path represents a collection. ", _jsx(_components.code, { children: "/books" }), " is the collection; ", _jsx(_components.code, { children: "/books/123" }), " is a member of that collection."] }), "\n", _jsxs(_components.li, { children: ["Predictability: Consumers can guess that ", _jsx(_components.code, { children: "/books" }), " lists resources and ", _jsx(_components.code, { children: "/books/{id}" }), " fetches one."] }), "\n", _jsxs(_components.li, { children: ["Extensibility: Nested resources follow naturally: ", _jsx(_components.code, { children: "/books/123/reviews" }), "."] }), "\n"] }), "\n", _jsx(_components.h4, { id: "rule-2-use-lowercase-with-hyphens", children: "Rule 2: Use Lowercase with Hyphens" }), "\n", _jsx(_components.p, { children: "Use lowercase letters and hyphens for multi-word resource names:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: "/api/v1/user-profiles\n/api/v1/order-items\n/api/v1/payment-methods\n\n/api/v1/UserProfiles # PascalCase: case sensitivity issues across systems\n/api/v1/user_profiles # Underscores: less URL-friendly, harder to type\n/api/v1/userprofiles # No separator: harder to read\n" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Why lowercase and hyphens?" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["Case sensitivity: Some systems treat ", _jsx(_components.code, { children: "User" }), " and ", _jsx(_components.code, { children: "user" }), " as different. Lowercase avoids ambiguity."] }), "\n", _jsx(_components.li, { children: "Readability: Hyphens are more visible than underscores in URLs, especially when underlined as links." }), "\n", _jsx(_components.li, { children: "Typing: Hyphens are easier to type on mobile keyboards." }), "\n"] }), "\n", _jsx(_components.h4, { id: "rule-3-use-ids-or-slugs-for-resource-identifiers", children: "Rule 3: Use IDs or Slugs for Resource Identifiers" }), "\n", _jsx(_components.p, { children: "When referencing a specific resource in the path, use either:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Numeric or UUID IDs" }), " for internal references: ", _jsx(_components.code, { children: "/api/v1/users/usr_123abc" })] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Slugs" }), " for human-readable, SEO-friendly URLs: ", _jsx(_components.code, { children: "/api/v1/articles/how-to-design-apis" })] }), "\n"] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Slug conversion rules:" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: "Original: \"Harry Potter and the Chamber of Secrets\"\nStep 1: Convert to lowercase: \"harry potter and the chamber of secrets\"\nStep 2: Replace spaces with hyphens: \"harry-potter-and-the-chamber-of-secrets\"\nStep 3: Remove special characters: \"harry-potter-and-the-chamber-of-secrets\"\n\nResult: /api/v1/books/harry-potter-and-the-chamber-of-secrets\n" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "When to use slugs vs IDs:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Use slugs for public-facing resources where readability matters (blog posts, products)." }), "\n", _jsx(_components.li, { children: "Use IDs for internal APIs or when the identifier is not human-meaningful (user IDs, order IDs)." }), "\n", _jsxs(_components.li, { children: ["Consider supporting both: ", _jsx(_components.code, { children: "/api/v1/articles/{slugOrId}" }), " with logic to resolve either."] }), "\n"] }), "\n", _jsx(_components.h3, { id: "hierarchical-paths", children: "Hierarchical Paths" }), "\n", _jsx(_components.p, { children: "Forward slashes in the path denote hierarchical relationships between resources:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: "/api/v1/organizations/123/projects/456/tasks/789\n│ │ │ └─ Task resource (child of project)\n│ │ └─ Project resource (child of organization)\n│ └─ Organization resource (top-level)\n" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Design guidelines for hierarchical paths:" }) }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Start with top-level resources:" }), " ", _jsx(_components.code, { children: "/organizations" }), ", ", _jsx(_components.code, { children: "/users" }), ", ", _jsx(_components.code, { children: "/products" }), "."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Nest only when there is a strong ownership relationship:" }), " A task belongs to a project; a project belongs to an organization."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Avoid deep nesting:" }), " More than three levels (", _jsx(_components.code, { children: "/a/b/c/d" }), ") becomes hard to work with."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Consider flat alternatives:" }), " Instead of ", _jsx(_components.code, { children: "/organizations/123/projects" }), ", you could use ", _jsx(_components.code, { children: "/projects?organizationId=123" }), "."] }), "\n"] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "When to nest vs. when to flatten:" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "hljs language-mermaid", "data-mermaid": "true", children: "flowchart TD\n Start[Designing a resource path] --> Q1{Is there a strong ownership relationship?}\n Q1 -->|Yes| Q2{Will consumers frequently access the child resource via the parent?}\n Q1 -->|No| Flat[Use flat path with query param]\n Q2 -->|Yes| Nest[Use nested path]\n Q2 -->|No| Flat\n" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Examples:" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: "Nested (strong ownership, frequent parent access):\n/api/v1/organizations/123/projects\n/api/v1/projects/456/tasks\n\nFlat (weak relationship, independent access):\n/api/v1/tasks?projectId=456\n/api/v1/members?organizationId=123\n\nOver-nested (hard to work with):\n/api/v1/organizations/123/projects/456/tasks/789/comments/101/replies\n" }) }), "\n", _jsx(_components.h2, { id: "idempotency-and-http-methods", children: "Idempotency and HTTP Methods" }), "\n", _jsx(_components.p, { children: "Idempotency is a critical concept for API design, especially for retry logic, distributed systems, and client resilience." }), "\n", _jsx(_components.h3, { id: "what-is-idempotency", children: "What Is Idempotency" }), "\n", _jsxs(_components.blockquote, { children: ["\n", _jsxs(_components.p, { children: ["An operation is ", _jsx(_components.strong, { children: "idempotent" }), " if performing it multiple times has the same effect as performing it once."] }), "\n"] }), "\n", _jsx(_components.p, { children: "In API terms: If a client sends the same request multiple times (due to network retries, user double-clicks, or bugs), the server's state after the first successful request should be the same as after the tenth." }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Why idempotency matters:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Network reliability:" }), " HTTP requests can fail or time out. Clients may retry. Idempotent operations ensure retries do not cause unintended side effects."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "User experience:" }), " Users may double-click a submit button. Idempotency prevents duplicate creations."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Distributed systems:" }), " In microservices, the same event might be processed multiple times. Idempotency ensures consistency."] }), "\n"] }), "\n", _jsx(_components.h3, { id: "idempotency-by-http-method", children: "Idempotency by HTTP Method" }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Method" }), _jsx(_components.th, { children: "Idempotent" }), _jsx(_components.th, { children: "Why" }), _jsx(_components.th, { children: "Example" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "GET" }) }), _jsx(_components.td, { children: "Yes" }), _jsxs(_components.td, { children: ["Fetching data does not change server state. Multiple ", _jsx(_components.code, { children: "GET" }), " requests return the same representation (assuming no concurrent updates)."] }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "GET /users/123" }), " returns the same user data whether called once or 100 times."] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "HEAD" }) }), _jsx(_components.td, { children: "Yes" }), _jsxs(_components.td, { children: ["Like ", _jsx(_components.code, { children: "GET" }), ", but returns headers only. No state change."] }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "HEAD /users/123" }), " checks if a resource exists without fetching it."] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "PUT" }) }), _jsx(_components.td, { children: "Yes" }), _jsx(_components.td, { children: "Replacing a resource with the same payload yields the same result." }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "PUT /users/123" }), " with ", _jsx(_components.code, { children: "{\"name\": \"Alice\"}" }), " sets the name to \"Alice\" regardless of how many times it is called."] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "DELETE" }) }), _jsx(_components.td, { children: "Yes" }), _jsx(_components.td, { children: "Deleting a resource once or multiple times results in the resource being absent." }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "DELETE /users/123" }), " removes the user. Subsequent calls return ", _jsx(_components.code, { children: "404" }), ", but the state (user absent) is unchanged."] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "POST" }) }), _jsx(_components.td, { children: "No" }), _jsxs(_components.td, { children: ["Each ", _jsx(_components.code, { children: "POST" }), " typically creates a new resource with a new ID. Multiple calls create multiple resources."] }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "POST /users" }), " with ", _jsx(_components.code, { children: "{\"name\": \"Alice\"}" }), " creates a new user each time."] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "PATCH" }) }), _jsx(_components.td, { children: "Depends" }), _jsx(_components.td, { children: "Idempotency depends on the patch operation. See detailed section below." }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "PATCH /users/123" }), " with ", _jsx(_components.code, { children: "{\"name\": \"Alice\"}" }), " is idempotent; with ", _jsx(_components.code, { children: "{\"viewCount\": \"+1\"}" }), " is not."] })] })] })] }), "\n", _jsx(_components.h3, { id: "patch-idempotency-it-depends", children: "PATCH Idempotency: It Depends" }), "\n", _jsxs(_components.p, { children: ["Per HTTP specifications (RFC 5789, RFC 7231), the ", _jsx(_components.code, { children: "PATCH" }), " method is ", _jsx(_components.strong, { children: "not guaranteed to be idempotent" }), ". Whether a ", _jsx(_components.code, { children: "PATCH" }), " request is idempotent depends entirely on the payload format and server logic."] }), "\n", _jsx(_components.h4, { id: "idempotent-patch-examples", children: "Idempotent PATCH Examples" }), "\n", _jsx(_components.p, { children: "These operations produce the same result regardless of how many times they are applied:" }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-comment", children: "// Replace a field - always results in name = \"Alice\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"op\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"replace\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"path\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"/name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"value\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Alice\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// Set a value unconditionally" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"op\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"set\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"path\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"/status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"value\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"archived\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// JSON Patch format (RFC 6902)" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "[" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"op\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"replace\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"path\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"/email\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"value\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"alice@example.com\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "]" }), "\n"] }) }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Why these are idempotent:" }), " The operation sets a specific value. Applying it multiple times does not change the outcome after the first application."] }), "\n", _jsx(_components.h4, { id: "non-idempotent-patch-examples", children: "Non-Idempotent PATCH Examples" }), "\n", _jsx(_components.p, { children: "These operations produce different results with each application:" }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-comment", children: "// Increment a counter - each call changes the value" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"op\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"add\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"path\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"/viewCount\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"value\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "1" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// Append to a list - each call adds a new item" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"op\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"add\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"path\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"/tags/-\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"value\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"new-tag\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// Conditional update - outcome depends on current state" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"op\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"test-and-set\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"path\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"/status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"if\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"pending\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"value\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"approved\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Why these are not idempotent:" }), " The operation's effect depends on the current state or accumulates with each application."] }), "\n", _jsx(_components.h4, { id: "practical-guidance-for-patch", children: "Practical Guidance for PATCH" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Document idempotency:" }), " If your ", _jsx(_components.code, { children: "PATCH" }), " endpoint is idempotent, state that clearly in your documentation. If not, warn consumers about retry behavior."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Prefer idempotent operations:" }), " When possible, design ", _jsx(_components.code, { children: "PATCH" }), " payloads to be idempotent. Use \"set\" semantics instead of \"increment\" or \"append.\""] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Support idempotency keys:" }), " For non-idempotent operations that must be retry-safe, allow clients to send an ", _jsx(_components.code, { children: "Idempotency-Key" }), " header. Your server can cache the response for a given key and return the cached result on retry."] }), "\n"] }), "\n"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "hljs language-http", children: "PATCH /api/v1/orders/123\nIdempotency-Key: abc123xyz\nContent-Type: application/json\n\n{ \"status\": \"shipped\" }\n" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-javascript", children: [_jsx(_components.span, { className: "hljs-comment", children: "// Server-side pseudocode" }), "\n", _jsx(_components.span, { className: "hljs-keyword", children: "if" }), " (cache.", _jsx(_components.span, { className: "hljs-title function_", children: "has" }), "(req.", _jsx(_components.span, { className: "hljs-property", children: "headers" }), "[", _jsx(_components.span, { className: "hljs-string", children: "'idempotency-key'" }), "])) {\n ", _jsx(_components.span, { className: "hljs-keyword", children: "return" }), " cache.", _jsx(_components.span, { className: "hljs-title function_", children: "get" }), "(req.", _jsx(_components.span, { className: "hljs-property", children: "headers" }), "[", _jsx(_components.span, { className: "hljs-string", children: "'idempotency-key'" }), "]);\n}\n", _jsx(_components.span, { className: "hljs-keyword", children: "const" }), " result = ", _jsx(_components.span, { className: "hljs-keyword", children: "await" }), " ", _jsx(_components.span, { className: "hljs-title function_", children: "processPatch" }), "(req.", _jsx(_components.span, { className: "hljs-property", children: "body" }), ");\ncache.", _jsx(_components.span, { className: "hljs-title function_", children: "set" }), "(req.", _jsx(_components.span, { className: "hljs-property", children: "headers" }), "[", _jsx(_components.span, { className: "hljs-string", children: "'idempotency-key'" }), "], result, { ", _jsx(_components.span, { className: "hljs-attr", children: "ttl" }), ": ", _jsx(_components.span, { className: "hljs-number", children: "3600" }), " });\n", _jsx(_components.span, { className: "hljs-keyword", children: "return" }), " result;\n"] }) }), "\n", _jsx(_components.h3, { id: "post-for-custom-actions", children: "POST for Custom Actions" }), "\n", _jsxs(_components.p, { children: ["The ", _jsx(_components.code, { children: "POST" }), " method serves two distinct purposes in REST API design:"] }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Create a new resource" }), " (standard CRUD operation)"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Execute a custom action" }), " that does not fit CRUD semantics"] }), "\n"] }), "\n", _jsx(_components.h4, { id: "when-to-use-post-for-custom-actions", children: "When to Use POST for Custom Actions" }), "\n", _jsxs(_components.p, { children: ["Use ", _jsx(_components.code, { children: "POST" }), " for custom actions when:"] }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "The operation does not map cleanly to create, read, update, or delete." }), "\n", _jsx(_components.li, { children: "The operation triggers complex server-side logic beyond simple state changes." }), "\n", _jsx(_components.li, { children: "The operation may have side effects that are not obvious from the resource representation." }), "\n"] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Examples of custom actions:" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: "# Send a welcome email to a user\nPOST /api/v1/users/123/send-welcome-email\n\n# Archive an organization (triggers cascading deletes, notifications)\nPOST /api/v1/organizations/123/archive\n\n# Clone a project (copies tasks, preserves assignments, sends notifications)\nPOST /api/v1/projects/456/clone\n\n# Approve a pending request (changes state and triggers workflow)\nPOST /api/v1/requests/789/approve\n\n# Generate a report (long-running operation, may return a job ID)\nPOST /api/v1/reports/generate\n" }) }), "\n", _jsx(_components.h4, { id: "designing-custom-action-endpoints", children: "Designing Custom Action Endpoints" }), "\n", _jsx(_components.p, { children: "Follow these patterns for custom action endpoints:" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Use a descriptive path segment:" }), " Place the action name after the resource identifier."] }), "\n"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: " POST /api/v1/users/123/send-welcome-email\n POST /api/v1/send-welcome-email?userId=123 # Action should be in path, not query\n" }) }), "\n", _jsxs(_components.ol, { start: "2", children: ["\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Use POST, not GET:" }), " Custom actions typically change state or trigger side effects. ", _jsx(_components.code, { children: "GET" }), " should be safe and idempotent."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Document the action's effects:" }), " Clearly describe what the action does, what preconditions are required, and what the response means."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Return appropriate status codes:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "200 OK" }), " if the action updates an existing resource and returns it."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "201 Created" }), " if the action creates a new resource."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "202 Accepted" }), " if the action is asynchronous and returns a job ID."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "204 No Content" }), " if the action succeeds but has no response body."] }), "\n"] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Consider idempotency:" }), " If the action should be retry-safe, document whether it is idempotent or support idempotency keys."] }), "\n"] }), "\n"] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Example: Archive Organization" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "hljs language-http", children: "POST /api/v1/organizations/123/archive\nAuthorization: Bearer abc123\nContent-Type: application/json\n\n{}\n" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-comment", children: "// Response: 200 OK" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"id\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"org_123\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Acme Corp\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"archived\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"archivedAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T15:30:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"archivedBy\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"usr_456\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Server-side behavior:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Validates that the caller has permission to archive the organization." }), "\n", _jsxs(_components.li, { children: ["Updates the organization's ", _jsx(_components.code, { children: "status" }), " to ", _jsx(_components.code, { children: "\"archived\"" }), "."] }), "\n", _jsxs(_components.li, { children: ["Sets ", _jsx(_components.code, { children: "archivedAt" }), " and ", _jsx(_components.code, { children: "archivedBy" }), " metadata."] }), "\n", _jsx(_components.li, { children: "Cascades to associated projects: marks them as archived or deletes them based on business rules." }), "\n", _jsx(_components.li, { children: "Sends notifications to organization members." }), "\n", _jsx(_components.li, { children: "Logs the action for audit purposes." }), "\n"] }), "\n", _jsxs(_components.p, { children: ["This is far more complex than a simple ", _jsx(_components.code, { children: "PATCH" }), " to update the ", _jsx(_components.code, { children: "status" }), " field. That complexity justifies a dedicated custom action endpoint."] }), "\n", _jsx(_components.h2, { id: "api-design-workflow-from-wireframes-to-endpoints", children: "API Design Workflow: From Wireframes to Endpoints" }), "\n", _jsx(_components.p, { children: "Do not start coding immediately. Design your API interface first. This upfront investment saves time later by preventing costly refactors and ensuring your API meets consumer needs." }), "\n", _jsx(_components.h3, { id: "step-1-start-with-uiwireframes", children: "Step 1: Start with UI/Wireframes" }), "\n", _jsx(_components.p, { children: "Look at Figma designs, user stories, or product requirements. Understand how end users interact with your platform. This reveals:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "What data users see on each screen" }), "\n", _jsx(_components.li, { children: "What actions users can perform (create, edit, delete, filter, sort)" }), "\n", _jsx(_components.li, { children: "How resources relate to each other (organizations contain projects, projects contain tasks)" }), "\n"] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Example: Project Management Platform" }) }), "\n", _jsx(_components.p, { children: "Imagine you are building a platform like Linear or Jira. The wireframes show:" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Organization Dashboard:" }), " Lists organizations the user belongs to. Each organization card shows name, status, and member count."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Project List:" }), " Within an organization, shows projects with name, status, progress, and due date."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Task Board:" }), " Within a project, shows tasks in columns (To Do, In Progress, Done). Each task shows title, assignee, priority, and due date."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Task Detail:" }), " Clicking a task opens a modal with full details, comments, and attachments."] }), "\n"] }), "\n", _jsx(_components.p, { children: "From these wireframes, you can infer the API requirements:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["List organizations → ", _jsx(_components.code, { children: "GET /organizations" })] }), "\n", _jsxs(_components.li, { children: ["Create organization → ", _jsx(_components.code, { children: "POST /organizations" })] }), "\n", _jsxs(_components.li, { children: ["List projects for an organization → ", _jsx(_components.code, { children: "GET /organizations/123/projects" })] }), "\n", _jsxs(_components.li, { children: ["Create task → ", _jsx(_components.code, { children: "POST /projects/456/tasks" })] }), "\n", _jsxs(_components.li, { children: ["Update task status → ", _jsx(_components.code, { children: "PATCH /tasks/789" })] }), "\n", _jsxs(_components.li, { children: ["Archive organization → Custom action: ", _jsx(_components.code, { children: "POST /organizations/123/archive" })] }), "\n"] }), "\n", _jsx(_components.h3, { id: "step-2-identify-resources-nouns", children: "Step 2: Identify Resources (Nouns)" }), "\n", _jsx(_components.p, { children: "Extract nouns from requirements. These become your top-level API resources." }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Brainstorming session:" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: "Product manager: \"Users can create organizations, invite members, and manage projects.\"\n→ Resources: users, organizations, projects\n\nProduct manager: \"Each project has tasks with titles, descriptions, assignees, and due dates.\"\n→ Resources: tasks\n\nProduct manager: \"Tasks can have comments, attachments, and tags.\"\n→ Resources: comments, attachments, tags\n\nProduct manager: \"Users can filter tasks by assignee, priority, or due date.\"\n→ Query parameters: assigneeId, priority, dueDateRange\n" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Prioritize resources:" }) }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Core resources:" }), " organizations, projects, tasks (required for MVP)"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Secondary resources:" }), " comments, attachments, tags (can be added later)"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Utility resources:" }), " users, roles, permissions (may be handled by a separate auth service)"] }), "\n"] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Document resources:" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-markdown", children: [_jsx(_components.span, { className: "hljs-section", children: "# API Resources" }), "\n\n", _jsx(_components.span, { className: "hljs-section", children: "## Organization" }), "\n", _jsx(_components.span, { className: "hljs-bullet", children: "-" }), " Represents a company or team\n", _jsx(_components.span, { className: "hljs-bullet", children: "-" }), " Fields: id, name, status, description, createdAt, updatedAt\n", _jsx(_components.span, { className: "hljs-bullet", children: "-" }), " Relationships: has many projects, has many members\n\n", _jsx(_components.span, { className: "hljs-section", children: "## Project" }), "\n", _jsx(_components.span, { className: "hljs-bullet", children: "-" }), " Represents a body of work within an organization\n", _jsx(_components.span, { className: "hljs-bullet", children: "-" }), " Fields: id, name, organizationId, status, description, createdAt, updatedAt\n", _jsx(_components.span, { className: "hljs-bullet", children: "-" }), " Relationships: belongs to organization, has many tasks\n\n", _jsx(_components.span, { className: "hljs-section", children: "## Task" }), "\n", _jsx(_components.span, { className: "hljs-bullet", children: "-" }), " Represents a unit of work within a project\n", _jsx(_components.span, { className: "hljs-bullet", children: "-" }), " Fields: id, title, projectId, status, priority, assignedTo, dueDate, description, createdAt, updatedAt\n", _jsx(_components.span, { className: "hljs-bullet", children: "-" }), " Relationships: belongs to project, assigned to user, has many comments\n"] }) }), "\n", _jsx(_components.h3, { id: "step-3-design-database-schema", children: "Step 3: Design Database Schema" }), "\n", _jsx(_components.p, { children: "Map resources to database tables. This step ensures your API design aligns with your data model." }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Example schema for project management platform:" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "hljs language-mermaid", "data-mermaid": "true", children: "classDiagram\n direction LR\n\n class Organization {\n <>\n id: string (PK)\n name: string (unique)\n status: enum(\"active\", \"archived\")\n description: string?\n createdAt: timestamp\n updatedAt: timestamp\n }\n\n class Project {\n <>\n id: string (PK)\n name: string\n organizationId: string (FK → Organization.id)\n status: enum(\"planned\", \"in-progress\", \"completed\")\n description: string?\n createdAt: timestamp\n updatedAt: timestamp\n }\n\n class Task {\n <>\n id: string (PK)\n title: string\n projectId: string (FK → Project.id)\n status: enum(\"pending\", \"in-progress\", \"completed\")\n priority: enum(\"low\", \"medium\", \"high\")\n assignedTo: string? (FK → User.id)\n assignedAt: timestamp?\n dueDate: timestamp?\n description: string?\n createdAt: timestamp\n updatedAt: timestamp\n }\n\n class User {\n <>\n id: string (PK)\n email: string (unique)\n name: string\n role: enum(\"member\", \"admin\", \"owner\")\n createdAt: timestamp\n updatedAt: timestamp\n }\n\n Organization \"1\" --> \"*\" Project : manages\n Project \"1\" --> \"*\" Task : contains\n User \"*\" --> \"*\" Organization : member of\n User \"1\" --> \"*\" Task : assigned to\n" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Key schema design decisions:" }) }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Use UUIDs for IDs:" }), " ", _jsx(_components.code, { children: "string" }), " type with UUID format. Avoid auto-increment integers for distributed systems."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Include timestamps:" }), " ", _jsx(_components.code, { children: "createdAt" }), " and ", _jsx(_components.code, { children: "updatedAt" }), " for auditing and sorting."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Use enums for status fields:" }), " Constrain values at the database level."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Make optional fields nullable:" }), " ", _jsx(_components.code, { children: "description?" }), ", ", _jsx(_components.code, { children: "assignedTo?" }), " indicate fields that may be absent."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Define foreign keys explicitly:" }), " Clarify relationships for documentation and tooling."] }), "\n"] }), "\n", _jsx(_components.h3, { id: "step-4-identify-actions-crud--custom", children: "Step 4: Identify Actions (CRUD + Custom)" }), "\n", _jsx(_components.p, { children: "For each resource, list the required operations. Start with CRUD, then add custom actions." }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Organization actions:" }) }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Action" }), _jsx(_components.th, { children: "HTTP Method" }), _jsx(_components.th, { children: "Endpoint" }), _jsx(_components.th, { children: "Description" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: "List organizations" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "GET" }) }), _jsx(_components.td, { children: _jsx(_components.code, { children: "/organizations" }) }), _jsx(_components.td, { children: "Return paginated list of organizations the user can access" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Create organization" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "POST" }) }), _jsx(_components.td, { children: _jsx(_components.code, { children: "/organizations" }) }), _jsx(_components.td, { children: "Create a new organization" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Get organization" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "GET" }) }), _jsx(_components.td, { children: _jsx(_components.code, { children: "/organizations/{id}" }) }), _jsx(_components.td, { children: "Return details of a specific organization" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Update organization" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "PATCH" }) }), _jsx(_components.td, { children: _jsx(_components.code, { children: "/organizations/{id}" }) }), _jsx(_components.td, { children: "Partially update organization fields" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Delete organization" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "DELETE" }) }), _jsx(_components.td, { children: _jsx(_components.code, { children: "/organizations/{id}" }) }), _jsx(_components.td, { children: "Soft-delete or hard-delete an organization" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Archive organization" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "POST" }) }), _jsx(_components.td, { children: _jsx(_components.code, { children: "/organizations/{id}/archive" }) }), _jsx(_components.td, { children: "Custom action: archive organization and cascade to projects" })] })] })] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Project actions:" }) }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Action" }), _jsx(_components.th, { children: "HTTP Method" }), _jsx(_components.th, { children: "Endpoint" }), _jsx(_components.th, { children: "Description" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: "List projects" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "GET" }) }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "/projects" }), " or ", _jsx(_components.code, { children: "/organizations/{orgId}/projects" })] }), _jsx(_components.td, { children: "Return paginated list of projects" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Create project" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "POST" }) }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "/projects" }), " or ", _jsx(_components.code, { children: "/organizations/{orgId}/projects" })] }), _jsx(_components.td, { children: "Create a new project" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Get project" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "GET" }) }), _jsx(_components.td, { children: _jsx(_components.code, { children: "/projects/{id}" }) }), _jsx(_components.td, { children: "Return details of a specific project" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Update project" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "PATCH" }) }), _jsx(_components.td, { children: _jsx(_components.code, { children: "/projects/{id}" }) }), _jsx(_components.td, { children: "Partially update project fields" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Delete project" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "DELETE" }) }), _jsx(_components.td, { children: _jsx(_components.code, { children: "/projects/{id}" }) }), _jsx(_components.td, { children: "Delete a project" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Clone project" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "POST" }) }), _jsx(_components.td, { children: _jsx(_components.code, { children: "/projects/{id}/clone" }) }), _jsx(_components.td, { children: "Custom action: duplicate a project with its tasks" })] })] })] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Task actions:" }) }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Action" }), _jsx(_components.th, { children: "HTTP Method" }), _jsx(_components.th, { children: "Endpoint" }), _jsx(_components.th, { children: "Description" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: "List tasks" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "GET" }) }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "/tasks" }), " or ", _jsx(_components.code, { children: "/projects/{projectId}/tasks" })] }), _jsx(_components.td, { children: "Return paginated, filterable list of tasks" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Create task" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "POST" }) }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "/tasks" }), " or ", _jsx(_components.code, { children: "/projects/{projectId}/tasks" })] }), _jsx(_components.td, { children: "Create a new task" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Get task" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "GET" }) }), _jsx(_components.td, { children: _jsx(_components.code, { children: "/tasks/{id}" }) }), _jsx(_components.td, { children: "Return details of a specific task" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Update task" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "PATCH" }) }), _jsx(_components.td, { children: _jsx(_components.code, { children: "/tasks/{id}" }) }), _jsx(_components.td, { children: "Partially update task fields" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Delete task" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "DELETE" }) }), _jsx(_components.td, { children: _jsx(_components.code, { children: "/tasks/{id}" }) }), _jsx(_components.td, { children: "Delete a task" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Move task" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "POST" }) }), _jsx(_components.td, { children: _jsx(_components.code, { children: "/tasks/{id}/move" }) }), _jsx(_components.td, { children: "Custom action: change task's project or position" })] })] })] }), "\n", _jsx(_components.h3, { id: "step-5-design-the-interface", children: "Step 5: Design the Interface" }), "\n", _jsx(_components.p, { children: "Use a tool like Insomnia, Postman, or Stoplight to design endpoints before writing code. Focus on:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Route structure and HTTP methods" }), "\n", _jsx(_components.li, { children: "Request headers, query parameters, and body schema" }), "\n", _jsx(_components.li, { children: "Response status codes, headers, and body schema" }), "\n", _jsx(_components.li, { children: "Error response format" }), "\n", _jsx(_components.li, { children: "Pagination, filtering, and sorting parameters" }), "\n"] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Example: Designing the Create Organization endpoint in Insomnia" }) }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Create a new request:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["Method: ", _jsx(_components.code, { children: "POST" })] }), "\n", _jsxs(_components.li, { children: ["URL: ", _jsx(_components.code, { children: "http://localhost:3000/api/v1/organizations" })] }), "\n"] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Define request headers:" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: "Content-Type: application/json\nAuthorization: Bearer \n" }) }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Define request body (JSON):" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Acme Corp\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"active\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Leading provider of widgets\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Define expected response:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["Status: ", _jsx(_components.code, { children: "201 Created" })] }), "\n", _jsx(_components.li, { children: "Body:" }), "\n"] }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"id\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"org_123abc\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Acme Corp\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"active\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Leading provider of widgets\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"createdAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T10:30:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"updatedAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T10:30:00Z\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Define error responses:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "400 Bad Request" }), ": Validation errors"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "401 Unauthorized" }), ": Missing or invalid token"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "403 Forbidden" }), ": User lacks permission to create organizations"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "409 Conflict" }), ": Organization name already exists"] }), "\n"] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Document the endpoint:" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-markdown", children: [_jsx(_components.span, { className: "hljs-section", children: "## Create Organization" }), "\n\n", _jsx(_components.span, { className: "hljs-code", children: "`POST /api/v1/organizations`" }), "\n\nCreates a new organization. The caller must have the ", _jsx(_components.span, { className: "hljs-code", children: "`org:create`" }), " permission.\n\n", _jsx(_components.span, { className: "hljs-section", children: "### Request" }), "\n\n", _jsx(_components.span, { className: "hljs-strong", children: "**Headers**" }), "\n", _jsx(_components.span, { className: "hljs-bullet", children: "-" }), " ", _jsx(_components.span, { className: "hljs-code", children: "`Authorization: Bearer `" }), " (required)\n", _jsx(_components.span, { className: "hljs-bullet", children: "-" }), " ", _jsx(_components.span, { className: "hljs-code", children: "`Content-Type: application/json`" }), " (required)\n\n", _jsx(_components.span, { className: "hljs-strong", children: "**Body**" }), "\n", _jsx(_components.span, { className: "hljs-code", children: "```json\n{\n \"name\": \"string (required, 3-100 chars, unique)\",\n \"status\": \"enum: active|archived (optional, default: active)\",\n \"description\": \"string (optional, max 500 chars)\"\n}\n" })] }) }), "\n", _jsx(_components.h3, { id: "response", children: "Response" }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "201 Created" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"id\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"string\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"string\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"string\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"string|null\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"createdAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"ISO8601 timestamp\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"updatedAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"ISO8601 timestamp\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "400 Bad Request" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Validation failed\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"details\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "[" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"field\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"message\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Name is required\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "]" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n"] }), "\n"] }), "\n", _jsx(_components.p, { children: "This design-first approach ensures you think through the consumer experience before writing implementation code. It also creates living documentation that stays in sync with your API." }), "\n", _jsx(_components.h2, { id: "designing-organization-apis", children: "Designing Organization APIs" }), "\n", _jsxs(_components.p, { children: ["Let's design every endpoint for the ", _jsx(_components.code, { children: "organizations" }), " resource. We will use Insomnia-style examples, but the patterns apply to any API client or documentation tool."] }), "\n", _jsx(_components.h3, { id: "list-organizations-get", children: "List Organizations (GET)" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Endpoint:" }), " ", _jsx(_components.code, { children: "GET /api/v1/organizations" })] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Purpose:" }), " Return a paginated list of organizations the authenticated user can access."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Query parameters:" }) }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Parameter" }), _jsx(_components.th, { children: "Type" }), _jsx(_components.th, { children: "Required" }), _jsx(_components.th, { children: "Default" }), _jsx(_components.th, { children: "Description" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "page" }) }), _jsx(_components.td, { children: "integer" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "1" }) }), _jsx(_components.td, { children: "Page number (1-indexed)" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "limit" }) }), _jsx(_components.td, { children: "integer" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "20" }) }), _jsxs(_components.td, { children: ["Items per page (max: ", _jsx(_components.code, { children: "100" }), ")"] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "sortBy" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "\"createdAt\"" }) }), _jsxs(_components.td, { children: ["Field to sort by (", _jsx(_components.code, { children: "name" }), ", ", _jsx(_components.code, { children: "createdAt" }), ", ", _jsx(_components.code, { children: "updatedAt" }), ")"] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "sortOrder" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "\"descending\"" }) }), _jsxs(_components.td, { children: ["Sort direction (", _jsx(_components.code, { children: "ascending" }), ", ", _jsx(_components.code, { children: "descending" }), ")"] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "status" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: "-" }), _jsxs(_components.td, { children: ["Filter by status (", _jsx(_components.code, { children: "active" }), ", ", _jsx(_components.code, { children: "archived" }), ")"] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "search" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: "-" }), _jsx(_components.td, { children: "Filter by name or description (case-insensitive partial match)" })] })] })] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Request example:" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "hljs language-http", children: "GET /api/v1/organizations?page=1&limit=10&sortBy=createdAt&sortOrder=descending&status=active\nAuthorization: Bearer abc123\n" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Success response (200 OK):" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"data\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "[" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"id\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"org_123abc\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Acme Corp\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"active\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Leading provider of widgets\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"createdAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-01-15T10:30:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"updatedAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-01-15T10:30:00Z\"" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"id\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"org_456def\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Beta Industries\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"active\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Innovative solutions for modern businesses\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"createdAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-01-10T14:22:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"updatedAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-01-20T09:15:00Z\"" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "]" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"pagination\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"total\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "47" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"page\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "1" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"limit\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "10" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"totalPages\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "5" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"hasNextPage\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-literal", children: _jsx(_components.span, { className: "hljs-keyword", children: "true" }) }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"hasPrevPage\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-literal", children: _jsx(_components.span, { className: "hljs-keyword", children: "false" }) }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Response fields explained:" }) }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Field" }), _jsx(_components.th, { children: "Type" }), _jsx(_components.th, { children: "Description" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "data" }) }), _jsx(_components.td, { children: "array" }), _jsx(_components.td, { children: "The requested portion of organization records" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "pagination.total" }) }), _jsx(_components.td, { children: "integer" }), _jsx(_components.td, { children: "Total count of organizations matching the filter (ignoring pagination)" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "pagination.page" }) }), _jsx(_components.td, { children: "integer" }), _jsx(_components.td, { children: "Current page number (1-indexed)" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "pagination.limit" }) }), _jsx(_components.td, { children: "integer" }), _jsx(_components.td, { children: "Items per page" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "pagination.totalPages" }) }), _jsx(_components.td, { children: "integer" }), _jsx(_components.td, { children: "Total pages available for the current filter" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "pagination.hasNextPage" }) }), _jsx(_components.td, { children: "boolean" }), _jsx(_components.td, { children: "Whether there is a next page" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "pagination.hasPrevPage" }) }), _jsx(_components.td, { children: "boolean" }), _jsx(_components.td, { children: "Whether there is a previous page" })] })] })] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Error responses:" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-comment", children: "// 401 Unauthorized - Missing or invalid token" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Authentication required\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"AUTH_REQUIRED\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// 403 Forbidden - User lacks permission to list organizations" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Insufficient permissions\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"PERMISSION_DENIED\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// 400 Bad Request - Invalid query parameters" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Invalid request parameters\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"details\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "[" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"field\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"limit\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"message\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Limit must be between 1 and 100\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "]" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.h3, { id: "create-organization-post", children: "Create Organization (POST)" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Endpoint:" }), " ", _jsx(_components.code, { children: "POST /api/v1/organizations" })] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Purpose:" }), " Create a new organization. The authenticated user becomes the owner."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Request headers:" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: "Authorization: Bearer abc123\nContent-Type: application/json\n" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Request body:" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Acme Corp\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"active\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Leading provider of widgets\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Request body schema:" }) }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Field" }), _jsx(_components.th, { children: "Type" }), _jsx(_components.th, { children: "Required" }), _jsx(_components.th, { children: "Constraints" }), _jsx(_components.th, { children: "Description" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "name" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "Yes" }), _jsx(_components.td, { children: "3-100 chars, unique" }), _jsx(_components.td, { children: "Organization name" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "status" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "No" }), _jsxs(_components.td, { children: ["enum: ", _jsx(_components.code, { children: "active" }), ", ", _jsx(_components.code, { children: "archived" })] }), _jsxs(_components.td, { children: ["Initial status (default: ", _jsx(_components.code, { children: "active" }), ")"] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "description" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: "max 500 chars" }), _jsx(_components.td, { children: "Optional description" })] })] })] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Success response (201 Created):" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"id\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"org_123abc\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Acme Corp\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"active\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Leading provider of widgets\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"createdAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T10:30:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"updatedAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T10:30:00Z\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Why 201 Created?" }), " The request created a new resource. The response includes the full representation of the created resource."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Error responses:" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-comment", children: "// 400 Bad Request - Validation errors" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Validation failed\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"details\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "[" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"field\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"message\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Name is required\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"field\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"message\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Name must be at least 3 characters\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "]" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// 409 Conflict - Name already exists" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Organization name already exists\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"RESOURCE_CONFLICT\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"field\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"name\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// 403 Forbidden - User lacks permission to create organizations" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Insufficient permissions\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"PERMISSION_DENIED\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.h3, { id: "get-single-organization-get", children: "Get Single Organization (GET)" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Endpoint:" }), " ", _jsx(_components.code, { children: "GET /api/v1/organizations/{id}" })] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Purpose:" }), " Return details of a specific organization."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Path parameters:" }) }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Parameter" }), _jsx(_components.th, { children: "Type" }), _jsx(_components.th, { children: "Required" }), _jsx(_components.th, { children: "Description" })] }) }), _jsx(_components.tbody, { children: _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "id" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "Yes" }), _jsx(_components.td, { children: "Organization ID (UUID format)" })] }) })] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Request example:" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "hljs language-http", children: "GET /api/v1/organizations/org_123abc\nAuthorization: Bearer abc123\n" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Success response (200 OK):" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"id\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"org_123abc\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Acme Corp\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"active\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Leading provider of widgets\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"createdAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-01-15T10:30:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"updatedAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-01-15T10:30:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"memberCount\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "12" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"projectCount\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "5" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Note:" }), " The response includes computed fields (", _jsx(_components.code, { children: "memberCount" }), ", ", _jsx(_components.code, { children: "projectCount" }), ") that are derived from related resources. These are safe to include in a ", _jsx(_components.code, { children: "GET" }), " response because they do not require client-side joins."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Error responses:" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-comment", children: "// 404 Not Found - Organization does not exist or user lacks access" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Organization not found\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"RESOURCE_NOT_FOUND\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// 401 Unauthorized - Missing or invalid token" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Authentication required\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"AUTH_REQUIRED\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Important:" }), " Return ", _jsx(_components.code, { children: "404" }), " for both \"resource does not exist\" and \"user lacks permission to access this resource.\" This prevents information leakage about the existence of resources the user cannot access."] }), "\n", _jsx(_components.h3, { id: "update-organization-patch", children: "Update Organization (PATCH)" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Endpoint:" }), " ", _jsx(_components.code, { children: "PATCH /api/v1/organizations/{id}" })] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Purpose:" }), " Partially update an organization's fields."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Path parameters:" }) }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Parameter" }), _jsx(_components.th, { children: "Type" }), _jsx(_components.th, { children: "Required" }), _jsx(_components.th, { children: "Description" })] }) }), _jsx(_components.tbody, { children: _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "id" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "Yes" }), _jsx(_components.td, { children: "Organization ID" })] }) })] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Request body:" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"archived\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Request body rules:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Only include fields you want to update." }), "\n", _jsx(_components.li, { children: "Omitted fields remain unchanged." }), "\n", _jsxs(_components.li, { children: ["All fields follow the same validation rules as ", _jsx(_components.code, { children: "POST" }), "."] }), "\n"] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Success response (200 OK):" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"id\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"org_123abc\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Acme Corp\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"archived\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Leading provider of widgets\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"createdAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-01-15T10:30:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"updatedAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T15:30:00Z\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Note:" }), " The ", _jsx(_components.code, { children: "updatedAt" }), " timestamp changes to reflect the modification. The response includes the full updated resource."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Error responses:" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-comment", children: "// 400 Bad Request - Validation errors" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Validation failed\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"details\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "[" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"field\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"message\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Status must be one of: active, archived\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "]" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// 404 Not Found - Organization does not exist or user lacks access" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Organization not found\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"RESOURCE_NOT_FOUND\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// 403 Forbidden - User lacks permission to update this organization" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Insufficient permissions\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"PERMISSION_DENIED\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// 409 Conflict - Update would violate a constraint (e.g., duplicate name)" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Organization name already exists\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"RESOURCE_CONFLICT\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"field\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"name\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.h3, { id: "delete-organization-delete", children: "Delete Organization (DELETE)" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Endpoint:" }), " ", _jsx(_components.code, { children: "DELETE /api/v1/organizations/{id}" })] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Purpose:" }), " Delete an organization. This may be a soft delete (mark as deleted) or hard delete (remove from database), depending on your business requirements."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Path parameters:" }) }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Parameter" }), _jsx(_components.th, { children: "Type" }), _jsx(_components.th, { children: "Required" }), _jsx(_components.th, { children: "Description" })] }) }), _jsx(_components.tbody, { children: _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "id" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "Yes" }), _jsx(_components.td, { children: "Organization ID" })] }) })] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Request example:" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "hljs language-http", children: "DELETE /api/v1/organizations/org_123abc\nAuthorization: Bearer abc123\n" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Success response (204 No Content):" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: "(empty body)\n" }) }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Why 204 No Content?" }), " The resource has been deleted. There is no representation to return. Returning the deleted resource would be misleading because it no longer exists in the active dataset."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Error responses:" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-comment", children: "// 404 Not Found - Organization does not exist or user lacks access" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Organization not found\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"RESOURCE_NOT_FOUND\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// 403 Forbidden - User lacks permission to delete this organization" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Insufficient permissions\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"PERMISSION_DENIED\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// 409 Conflict - Organization has active projects that must be handled first" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Cannot delete organization with active projects\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"RESOURCE_CONFLICT\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"details\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"activeProjects\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "3" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"suggestion\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Archive or delete projects before deleting the organization\"" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.h3, { id: "custom-action-archive-organization", children: "Custom Action: Archive Organization" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Endpoint:" }), " ", _jsx(_components.code, { children: "POST /api/v1/organizations/{id}/archive" })] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Purpose:" }), " Archive an organization. This is a custom action because it triggers complex server-side logic beyond a simple status update."] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Why a custom action instead of PATCH?" }), " Archiving an organization may:"] }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: ["Update the organization's ", _jsx(_components.code, { children: "status" }), " to ", _jsx(_components.code, { children: "\"archived\"" }), "."] }), "\n", _jsx(_components.li, { children: "Cascade to associated projects: mark them as archived or delete them based on business rules." }), "\n", _jsx(_components.li, { children: "Revoke or downgrade member permissions." }), "\n", _jsx(_components.li, { children: "Send notifications to organization members." }), "\n", _jsx(_components.li, { children: "Log the action for audit purposes." }), "\n", _jsx(_components.li, { children: "Update search indexes to exclude archived organizations." }), "\n"] }), "\n", _jsx(_components.p, { children: "This complexity justifies a dedicated endpoint with clear semantics." }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Path parameters:" }) }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Parameter" }), _jsx(_components.th, { children: "Type" }), _jsx(_components.th, { children: "Required" }), _jsx(_components.th, { children: "Description" })] }) }), _jsx(_components.tbody, { children: _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "id" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "Yes" }), _jsx(_components.td, { children: "Organization ID" })] }) })] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Request body:" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"reason\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Company restructuring\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"archiveProjects\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-literal", children: _jsx(_components.span, { className: "hljs-keyword", children: "true" }) }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Request body schema:" }) }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Field" }), _jsx(_components.th, { children: "Type" }), _jsx(_components.th, { children: "Required" }), _jsx(_components.th, { children: "Description" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "reason" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: "Optional reason for archival (for audit logs)" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "archiveProjects" }) }), _jsx(_components.td, { children: "boolean" }), _jsx(_components.td, { children: "No" }), _jsxs(_components.td, { children: ["Whether to archive associated projects (default: ", _jsx(_components.code, { children: "true" }), ")"] })] })] })] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Success response (200 OK):" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"id\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"org_123abc\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Acme Corp\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"archived\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Leading provider of widgets\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"createdAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-01-15T10:30:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"updatedAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T15:30:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"archivedAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T15:30:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"archivedBy\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"usr_456def\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"archivedReason\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Company restructuring\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"affectedResources\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"projectsArchived\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "5" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"tasksArchived\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "42" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"membersNotified\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "12" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Why 200 OK instead of 201 Created?" }), " The action updated an existing resource (the organization) rather than creating a new one. The response includes the updated resource plus metadata about the action's effects."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Error responses:" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-comment", children: "// 400 Bad Request - Invalid request body" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Validation failed\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"details\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "[" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"field\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"archiveProjects\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"message\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"archiveProjects must be a boolean\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "]" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// 404 Not Found - Organization does not exist or user lacks access" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Organization not found\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"RESOURCE_NOT_FOUND\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// 403 Forbidden - User lacks permission to archive this organization" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Insufficient permissions\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"PERMISSION_DENIED\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// 409 Conflict - Organization is already archived" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Organization is already archived\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"RESOURCE_CONFLICT\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.h2, { id: "pagination-sorting-and-filtering", children: "Pagination, Sorting, and Filtering" }), "\n", _jsxs(_components.p, { children: ["List endpoints (", _jsx(_components.code, { children: "GET /resources" }), ") need three features to be usable at scale: pagination, sorting, and filtering."] }), "\n", _jsx(_components.h3, { id: "why-pagination-exists", children: "Why Pagination Exists" }), "\n", _jsx(_components.p, { children: "Returning all records in a single response does not scale. Consider an endpoint that lists tasks:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: "GET /api/v1/tasks\n" }) }), "\n", _jsx(_components.p, { children: "If your database contains 100,000 tasks, returning all of them in one response would:" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Consume excessive server resources:" }), " Serializing 100,000 JSON objects is CPU-intensive."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Consume excessive network bandwidth:" }), " A 50MB JSON response takes time to transmit."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Overwhelm the client:" }), " Parsing and rendering 100,000 items in a browser or mobile app is slow and memory-intensive."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Provide poor user experience:" }), " Users rarely need to see all 100,000 tasks at once."] }), "\n"] }), "\n", _jsx(_components.p, { children: "Pagination solves these problems by returning data in chunks." }), "\n", _jsx(_components.h3, { id: "pagination-response-structure", children: "Pagination Response Structure" }), "\n", _jsx(_components.p, { children: "Use a consistent structure for paginated responses:" }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"data\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "[" }), _jsx(_components.span, { className: "hljs-comment", children: "/* array of resource objects */" }), _jsx(_components.span, { className: "hljs-punctuation", children: "]" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"pagination\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"total\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "100000" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"page\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "1" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"limit\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "20" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"totalPages\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "5000" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"hasNextPage\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-literal", children: _jsx(_components.span, { className: "hljs-keyword", children: "true" }) }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"hasPrevPage\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-literal", children: _jsx(_components.span, { className: "hljs-keyword", children: "false" }) }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Field" }), _jsx(_components.th, { children: "Type" }), _jsx(_components.th, { children: "Description" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "data" }) }), _jsx(_components.td, { children: "array" }), _jsx(_components.td, { children: "The requested portion of records" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "pagination.total" }) }), _jsx(_components.td, { children: "integer" }), _jsx(_components.td, { children: "Total count of records matching the filter (ignoring pagination)" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "pagination.page" }) }), _jsx(_components.td, { children: "integer" }), _jsx(_components.td, { children: "Current page number (1-indexed)" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "pagination.limit" }) }), _jsx(_components.td, { children: "integer" }), _jsx(_components.td, { children: "Items per page" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "pagination.totalPages" }) }), _jsx(_components.td, { children: "integer" }), _jsx(_components.td, { children: "Total pages available for the current filter" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "pagination.hasNextPage" }) }), _jsx(_components.td, { children: "boolean" }), _jsx(_components.td, { children: "Whether there is a next page" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "pagination.hasPrevPage" }) }), _jsx(_components.td, { children: "boolean" }), _jsx(_components.td, { children: "Whether there is a previous page" })] })] })] }), "\n", _jsxs(_components.p, { children: [_jsxs(_components.strong, { children: ["Why include ", _jsx(_components.code, { children: "total" }), " and ", _jsx(_components.code, { children: "totalPages" }), "?"] }), " These fields enable UI features like:"] }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "\"Showing 1-20 of 100,000 tasks\"" }), "\n", _jsx(_components.li, { children: "Page number navigation: \"1 2 3 ... 5000\"" }), "\n", _jsx(_components.li, { children: "Progress indicators: \"Page 1 of 5000\"" }), "\n"] }), "\n", _jsxs(_components.p, { children: [_jsxs(_components.strong, { children: ["Why include ", _jsx(_components.code, { children: "hasNextPage" }), " and ", _jsx(_components.code, { children: "hasPrevPage" }), "?"] }), " These boolean fields simplify client logic for infinite scroll or \"Load more\" buttons. The client does not need to calculate whether a next page exists."] }), "\n", _jsx(_components.h3, { id: "pagination-in-practice", children: "Pagination in Practice" }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Query parameters:" }) }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Parameter" }), _jsx(_components.th, { children: "Type" }), _jsx(_components.th, { children: "Required" }), _jsx(_components.th, { children: "Default" }), _jsx(_components.th, { children: "Constraints" }), _jsx(_components.th, { children: "Description" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "page" }) }), _jsx(_components.td, { children: "integer" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "1" }) }), _jsxs(_components.td, { children: ["min: ", _jsx(_components.code, { children: "1" })] }), _jsx(_components.td, { children: "Page number (1-indexed)" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "limit" }) }), _jsx(_components.td, { children: "integer" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "20" }) }), _jsxs(_components.td, { children: ["min: ", _jsx(_components.code, { children: "1" }), ", max: ", _jsx(_components.code, { children: "100" })] }), _jsx(_components.td, { children: "Items per page" })] })] })] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Examples:" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "hljs language-http", children: "# Get first page with default limit (20 items)\nGET /api/v1/organizations\n\n# Get second page with custom limit (10 items)\nGET /api/v1/organizations?page=2&limit=10\n\n# Get last page (calculate page number from total/limit)\nGET /api/v1/organizations?page=5000&limit=20\n" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Server-side implementation considerations:" }) }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Validate parameters:" }), " Ensure ", _jsx(_components.code, { children: "page" }), " and ", _jsx(_components.code, { children: "limit" }), " are within acceptable ranges. Return ", _jsx(_components.code, { children: "400 Bad Request" }), " for invalid values."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Apply defaults:" }), " If the client omits ", _jsx(_components.code, { children: "page" }), " or ", _jsx(_components.code, { children: "limit" }), ", use sensible defaults (", _jsx(_components.code, { children: "page=1" }), ", ", _jsx(_components.code, { children: "limit=20" }), ")."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Enforce maximum limit:" }), " Prevent clients from requesting excessive data in a single response (e.g., ", _jsx(_components.code, { children: "limit=10000" }), "). Return an error or cap the limit."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Count efficiently:" }), " Calculating ", _jsx(_components.code, { children: "total" }), " requires a ", _jsx(_components.code, { children: "COUNT(*)" }), " query, which can be expensive on large tables. Consider:"] }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Caching the count for frequently accessed filters" }), "\n", _jsx(_components.li, { children: "Using approximate counts for very large datasets" }), "\n", _jsxs(_components.li, { children: ["Omitting ", _jsx(_components.code, { children: "total" }), " for endpoints where it is not critical"] }), "\n"] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Sort before paginating:" }), " Apply sorting before slicing the result set. Otherwise, page boundaries may shift between requests."] }), "\n"] }), "\n"] }), "\n", _jsx(_components.h3, { id: "sorting-in-list-apis", children: "Sorting in List APIs" }), "\n", _jsxs(_components.p, { children: ["Clients should control the order of results. Provide ", _jsx(_components.code, { children: "sortBy" }), " and ", _jsx(_components.code, { children: "sortOrder" }), " parameters."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Query parameters:" }) }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Parameter" }), _jsx(_components.th, { children: "Type" }), _jsx(_components.th, { children: "Required" }), _jsx(_components.th, { children: "Default" }), _jsx(_components.th, { children: "Allowed Values" }), _jsx(_components.th, { children: "Description" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "sortBy" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "\"createdAt\"" }) }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "name" }), ", ", _jsx(_components.code, { children: "createdAt" }), ", ", _jsx(_components.code, { children: "updatedAt" }), ", ", _jsx(_components.code, { children: "status" })] }), _jsx(_components.td, { children: "Field to sort by" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "sortOrder" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "\"descending\"" }) }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "ascending" }), ", ", _jsx(_components.code, { children: "descending" })] }), _jsx(_components.td, { children: "Sort direction" })] })] })] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Examples:" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "hljs language-http", children: "# Default sort: newest first\nGET /api/v1/organizations\n\n# Sort by name alphabetically\nGET /api/v1/organizations?sortBy=name&sortOrder=ascending\n\n# Sort by last updated, oldest first\nGET /api/v1/organizations?sortBy=updatedAt&sortOrder=ascending\n" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Server-side implementation:" }) }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Whitelist sortable fields:" }), " Only allow sorting on fields that are indexed and make sense for ordering. Reject unknown ", _jsx(_components.code, { children: "sortBy" }), " values with ", _jsx(_components.code, { children: "400 Bad Request" }), "."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Map client field names to database columns:" }), " The API may use ", _jsx(_components.code, { children: "createdAt" }), ", but the database column might be ", _jsx(_components.code, { children: "created_at" }), ". Handle this mapping internally."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Apply defaults:" }), " If the client omits ", _jsx(_components.code, { children: "sortBy" }), " or ", _jsx(_components.code, { children: "sortOrder" }), ", use sensible defaults (", _jsx(_components.code, { children: "sortBy=createdAt" }), ", ", _jsx(_components.code, { children: "sortOrder=descending" }), ")."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Combine with pagination:" }), " Apply sorting before slicing the result set for pagination."] }), "\n"] }), "\n"] }), "\n", _jsx(_components.h3, { id: "filtering-in-list-apis", children: "Filtering in List APIs" }), "\n", _jsx(_components.p, { children: "Clients should filter results by field values. Support filtering on commonly queried fields." }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Query parameters:" }) }), "\n", _jsx(_components.p, { children: "Use field names directly as query parameters. Support exact match, partial match, and range filters." }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Filter Type" }), _jsx(_components.th, { children: "Example" }), _jsx(_components.th, { children: "Description" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Exact match" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "?status=active" }) }), _jsxs(_components.td, { children: ["Return resources where ", _jsx(_components.code, { children: "status" }), " equals ", _jsx(_components.code, { children: "\"active\"" })] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Partial match" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "?search=acme" }) }), _jsxs(_components.td, { children: ["Return resources where ", _jsx(_components.code, { children: "name" }), " or ", _jsx(_components.code, { children: "description" }), " contains ", _jsx(_components.code, { children: "\"acme\"" }), " (case-insensitive)"] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Range (gte/lte)" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "?createdAt[gte]=2025-01-01&createdAt[lte]=2025-12-31" }) }), _jsx(_components.td, { children: "Return resources created in 2025" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: "Multiple values" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "?status=active,archived" }) }), _jsxs(_components.td, { children: ["Return resources where ", _jsx(_components.code, { children: "status" }), " is either ", _jsx(_components.code, { children: "\"active\"" }), " or ", _jsx(_components.code, { children: "\"archived\"" })] })] })] })] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Examples:" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "hljs language-http", children: "# Filter by status\nGET /api/v1/organizations?status=active\n\n# Search by name or description\nGET /api/v1/organizations?search=acme\n\n# Filter by date range\nGET /api/v1/organizations?createdAt[gte]=2025-01-01\n\n# Combine filters\nGET /api/v1/organizations?status=active&search=acme&sortBy=createdAt&sortOrder=descending\n" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Server-side implementation:" }) }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Whitelist filterable fields:" }), " Only allow filtering on fields that are indexed and safe to query. Reject unknown filter fields with ", _jsx(_components.code, { children: "400 Bad Request" }), "."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Sanitize input:" }), " Prevent injection attacks by parameterizing queries. Never interpolate user input directly into SQL."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Support multiple filter types:" }), " Implement exact match, partial match, and range filters for flexible querying."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Combine filters with AND logic:" }), " By default, combine multiple filters with AND. Support OR logic via a separate parameter if needed (e.g., ", _jsx(_components.code, { children: "?status=active,archived" }), ")."] }), "\n"] }), "\n"] }), "\n", _jsx(_components.h3, { id: "combining-parameters", children: "Combining Parameters" }), "\n", _jsx(_components.p, { children: "All three features work together:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "hljs language-http", children: "GET /api/v1/tasks?projectId=proj_456&status=pending&priority=high&sortBy=dueDate&sortOrder=ascending&page=1&limit=20\n" }) }), "\n", _jsx(_components.p, { children: "This request:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["Filters tasks to a specific project (", _jsx(_components.code, { children: "projectId=proj_456" }), ")"] }), "\n", _jsxs(_components.li, { children: ["Filters to pending tasks with high priority (", _jsx(_components.code, { children: "status=pending&priority=high" }), ")"] }), "\n", _jsxs(_components.li, { children: ["Sorts by due date, earliest first (", _jsx(_components.code, { children: "sortBy=dueDate&sortOrder=ascending" }), ")"] }), "\n", _jsxs(_components.li, { children: ["Returns the first page of 20 results (", _jsx(_components.code, { children: "page=1&limit=20" }), ")"] }), "\n"] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Design guidelines:" }) }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Document supported parameters:" }), " Clearly list which query parameters are supported for each endpoint."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Provide examples:" }), " Include example requests in your documentation to help consumers understand how to combine parameters."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Validate combinations:" }), " Some parameter combinations may not make sense (e.g., ", _jsx(_components.code, { children: "search" }), " with ", _jsx(_components.code, { children: "id" }), "). Return helpful errors for invalid combinations."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Consider performance:" }), " Complex filter combinations can be expensive. Use database indexes and query planning to optimize performance."] }), "\n"] }), "\n"] }), "\n", _jsx(_components.h2, { id: "designing-project-apis", children: "Designing Project APIs" }), "\n", _jsxs(_components.p, { children: ["Apply the same patterns to the ", _jsx(_components.code, { children: "projects" }), " resource. Consistency across resources reduces cognitive load for API consumers."] }), "\n", _jsx(_components.h3, { id: "create-project-post", children: "Create Project (POST)" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Endpoint:" }), " ", _jsx(_components.code, { children: "POST /api/v1/projects" })] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Purpose:" }), " Create a new project within an organization."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Request headers:" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: "Authorization: Bearer abc123\nContent-Type: application/json\n" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Request body:" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Website Redesign\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"organizationId\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"org_123abc\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"planned\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Refresh the company website with modern design and improved UX\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Request body schema:" }) }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Field" }), _jsx(_components.th, { children: "Type" }), _jsx(_components.th, { children: "Required" }), _jsx(_components.th, { children: "Constraints" }), _jsx(_components.th, { children: "Description" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "name" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "Yes" }), _jsx(_components.td, { children: "3-100 chars" }), _jsx(_components.td, { children: "Project name" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "organizationId" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "Yes" }), _jsx(_components.td, { children: "valid UUID" }), _jsx(_components.td, { children: "ID of the parent organization" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "status" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "No" }), _jsxs(_components.td, { children: ["enum: ", _jsx(_components.code, { children: "planned" }), ", ", _jsx(_components.code, { children: "in-progress" }), ", ", _jsx(_components.code, { children: "completed" })] }), _jsxs(_components.td, { children: ["Initial status (default: ", _jsx(_components.code, { children: "planned" }), ")"] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "description" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: "max 500 chars" }), _jsx(_components.td, { children: "Optional description" })] })] })] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Success response (201 Created):" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"id\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"proj_456def\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Website Redesign\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"organizationId\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"org_123abc\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"planned\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Refresh the company website with modern design and improved UX\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"createdAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T16:00:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"updatedAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T16:00:00Z\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Error responses:" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-comment", children: "// 400 Bad Request - Validation errors" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Validation failed\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"details\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "[" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"field\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"message\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Name is required\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"field\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"organizationId\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"message\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Invalid organization ID\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "]" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// 403 Forbidden - User lacks permission to create projects in this organization" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Insufficient permissions\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"PERMISSION_DENIED\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// 404 Not Found - Organization does not exist or user lacks access" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Organization not found\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"RESOURCE_NOT_FOUND\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.h3, { id: "list-projects-get", children: "List Projects (GET)" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Endpoint:" }), " ", _jsx(_components.code, { children: "GET /api/v1/projects" })] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Purpose:" }), " Return a paginated, filterable list of projects."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Query parameters:" }) }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Parameter" }), _jsx(_components.th, { children: "Type" }), _jsx(_components.th, { children: "Required" }), _jsx(_components.th, { children: "Default" }), _jsx(_components.th, { children: "Description" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "page" }) }), _jsx(_components.td, { children: "integer" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "1" }) }), _jsx(_components.td, { children: "Page number" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "limit" }) }), _jsx(_components.td, { children: "integer" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "20" }) }), _jsx(_components.td, { children: "Items per page" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "sortBy" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "\"createdAt\"" }) }), _jsx(_components.td, { children: "Field to sort by" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "sortOrder" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "\"descending\"" }) }), _jsx(_components.td, { children: "Sort direction" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "organizationId" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: "-" }), _jsx(_components.td, { children: "Filter by organization" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "status" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: "-" }), _jsx(_components.td, { children: "Filter by status" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "search" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: "-" }), _jsx(_components.td, { children: "Search by name or description" })] })] })] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Request example:" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "hljs language-http", children: "GET /api/v1/projects?organizationId=org_123abc&status=in-progress&limit=10\nAuthorization: Bearer abc123\n" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Success response (200 OK):" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"data\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "[" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"id\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"proj_456def\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Website Redesign\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"organizationId\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"org_123abc\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"in-progress\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Refresh the company website\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"createdAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T16:00:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"updatedAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T16:00:00Z\"" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "]" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"pagination\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"total\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "12" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"page\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "1" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"limit\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "10" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"totalPages\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "2" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"hasNextPage\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-literal", children: _jsx(_components.span, { className: "hljs-keyword", children: "true" }) }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"hasPrevPage\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-literal", children: _jsx(_components.span, { className: "hljs-keyword", children: "false" }) }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.h3, { id: "get-single-project-get", children: "Get Single Project (GET)" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Endpoint:" }), " ", _jsx(_components.code, { children: "GET /api/v1/projects/{id}" })] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Purpose:" }), " Return details of a specific project."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Path parameters:" }) }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Parameter" }), _jsx(_components.th, { children: "Type" }), _jsx(_components.th, { children: "Required" }), _jsx(_components.th, { children: "Description" })] }) }), _jsx(_components.tbody, { children: _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "id" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "Yes" }), _jsx(_components.td, { children: "Project ID" })] }) })] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Success response (200 OK):" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"id\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"proj_456def\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Website Redesign\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"organizationId\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"org_123abc\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"in-progress\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Refresh the company website\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"createdAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T16:00:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"updatedAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T16:00:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"taskCount\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "24" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"completedTaskCount\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "8" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"progress\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "33" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Note:" }), " Computed fields (", _jsx(_components.code, { children: "taskCount" }), ", ", _jsx(_components.code, { children: "completedTaskCount" }), ", ", _jsx(_components.code, { children: "progress" }), ") provide useful summary information without requiring client-side joins."] }), "\n", _jsx(_components.h3, { id: "update-project-patch", children: "Update Project (PATCH)" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Endpoint:" }), " ", _jsx(_components.code, { children: "PATCH /api/v1/projects/{id}" })] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Purpose:" }), " Partially update a project's fields."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Request body:" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"completed\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Website redesign launched successfully\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Success response (200 OK):" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"id\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"proj_456def\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Website Redesign\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"organizationId\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"org_123abc\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"completed\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Website redesign launched successfully\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"createdAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T16:00:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"updatedAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T18:30:00Z\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.h3, { id: "delete-project-delete", children: "Delete Project (DELETE)" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Endpoint:" }), " ", _jsx(_components.code, { children: "DELETE /api/v1/projects/{id}" })] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Purpose:" }), " Delete a project."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Success response (204 No Content):" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: "(empty body)\n" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Error response (409 Conflict):" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Cannot delete project with active tasks\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"RESOURCE_CONFLICT\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"details\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"activeTasks\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "5" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"suggestion\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Complete or delete tasks before deleting the project\"" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.h3, { id: "custom-action-clone-project", children: "Custom Action: Clone Project" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Endpoint:" }), " ", _jsx(_components.code, { children: "POST /api/v1/projects/{id}/clone" })] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Purpose:" }), " Clone a project, including its tasks and metadata."] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Why a custom action?" }), " Cloning a project is more complex than creating a new project with the same fields:"] }), "\n", _jsxs(_components.ol, { children: ["\n", _jsx(_components.li, { children: "Copy the project's metadata (name, description, status) with modifications (e.g., append \" - Copy\" to the name)." }), "\n", _jsx(_components.li, { children: "Duplicate all tasks associated with the project, preserving their structure but assigning new IDs." }), "\n", _jsx(_components.li, { children: "Preserve task assignments, comments, and attachments if applicable." }), "\n", _jsx(_components.li, { children: "Send notifications to project members about the clone." }), "\n", _jsx(_components.li, { children: "Log the action for audit purposes." }), "\n"] }), "\n", _jsx(_components.p, { children: "This complexity justifies a dedicated endpoint." }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Request body:" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Website Redesign - Copy\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"planned\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"includeTasks\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-literal", children: _jsx(_components.span, { className: "hljs-keyword", children: "true" }) }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"includeComments\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-literal", children: _jsx(_components.span, { className: "hljs-keyword", children: "false" }) }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Request body schema:" }) }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Field" }), _jsx(_components.th, { children: "Type" }), _jsx(_components.th, { children: "Required" }), _jsx(_components.th, { children: "Default" }), _jsx(_components.th, { children: "Description" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "name" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "\"{originalName} - Copy\"" }) }), _jsx(_components.td, { children: "Name for the cloned project" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "status" }) }), _jsx(_components.td, { children: "string" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "\"planned\"" }) }), _jsx(_components.td, { children: "Initial status for the clone" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "includeTasks" }) }), _jsx(_components.td, { children: "boolean" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "true" }) }), _jsx(_components.td, { children: "Whether to clone associated tasks" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "includeComments" }) }), _jsx(_components.td, { children: "boolean" }), _jsx(_components.td, { children: "No" }), _jsx(_components.td, { children: _jsx(_components.code, { children: "false" }) }), _jsx(_components.td, { children: "Whether to clone task comments" })] })] })] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Success response (201 Created):" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"id\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"proj_789ghi\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Website Redesign - Copy\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"organizationId\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"org_123abc\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"planned\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Refresh the company website\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"createdAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T19:00:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"updatedAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T19:00:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"clonedFrom\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"proj_456def\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"clonedAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T19:00:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"clonedBy\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"usr_456def\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"affectedResources\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"tasksCloned\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "24" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"commentsCloned\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "0" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Why 201 Created?" }), " The action created a new resource (the cloned project). The response includes the new resource plus metadata about the clone operation."] }), "\n", _jsx(_components.h2, { id: "consistency-across-resources", children: "Consistency Across Resources" }), "\n", _jsx(_components.p, { children: "Consistency is one of the most important characteristics of a well-designed API. When your API behaves predictably across resources, consumers can integrate faster with fewer mistakes." }), "\n", _jsx(_components.h3, { id: "json-field-naming", children: "JSON Field Naming" }), "\n", _jsxs(_components.p, { children: ["Always use ", _jsx(_components.code, { children: "camelCase" }), " for JSON field names:"] }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [" ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"createdAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T10:30:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"organizationId\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"org_123\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"created_at\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T10:30:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"organization_id\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"org_123\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), " ", _jsx(_components.span, { className: "hljs-comment", children: "// snake_case" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"CreatedAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T10:30:00Z\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"OrganizationId\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"org_123\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), " ", _jsx(_components.span, { className: "hljs-comment", children: "// PascalCase" }), "\n"] }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Why camelCase?" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "JavaScript convention: Most API consumers use JavaScript/TypeScript, where camelCase is standard." }), "\n", _jsx(_components.li, { children: "Consistency: Stick to one convention across your entire API." }), "\n", _jsx(_components.li, { children: "Tooling: Many JSON libraries and code generators expect camelCase." }), "\n"] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Exception:" }), " If your API primarily serves a language that uses a different convention (e.g., Python with snake_case), you may choose that convention. But be consistent within your API."] }), "\n", _jsx(_components.h3, { id: "payload-structure", children: "Payload Structure" }), "\n", _jsx(_components.p, { children: "Use consistent field names for the same concept across resources:" }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-comment", children: "// Organization payload" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Acme Corp\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Widget maker\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"active\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// Project payload - same field names" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"name\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Website Redesign\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Refresh the website\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"planned\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// Task payload - same field names" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"title\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Implement login\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Add user authentication\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"status\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"pending\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Note:" }), " Tasks use ", _jsx(_components.code, { children: "title" }), " instead of ", _jsx(_components.code, { children: "name" }), " because \"task title\" is more semantically accurate than \"task name.\" This is an acceptable deviation when the semantics differ."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Avoid inconsistent abbreviations:" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [" ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Details about the project\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"desc\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Details about the project\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), " ", _jsx(_components.span, { className: "hljs-comment", children: "// Unclear abbreviation" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"dsc\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Details about the project\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), " ", _jsx(_components.span, { className: "hljs-comment", children: "// Even less clear" }), "\n"] }) }), "\n", _jsx(_components.h3, { id: "route-patterns", children: "Route Patterns" }), "\n", _jsx(_components.p, { children: "Apply the same structure across resources:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: " /api/v1/organizations\n /api/v1/projects\n /api/v1/tasks\n\n /api/v1/organization // singular: inconsistent\n /api/v1/Project // PascalCase: inconsistent\n /api/v1/tasks_list // suffix: inconsistent\n" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Nested resource patterns:" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: " /api/v1/organizations/123/projects\n /api/v1/projects/456/tasks\n\n /api/v1/orgs/123/projs // inconsistent abbreviations\n /api/v1/organization/123/project // singular: inconsistent\n" }) }), "\n", _jsx(_components.h3, { id: "query-parameter-names", children: "Query Parameter Names" }), "\n", _jsx(_components.p, { children: "Use consistent parameter names for common operations:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: "# Pagination (all list endpoints)\n?page=1&limit=20\n\n# Sorting (all list endpoints)\n?sortBy=createdAt&sortOrder=descending\n\n# Filtering (all list endpoints)\n?status=active&search=acme\n\n# Date ranges (all list endpoints)\n?createdAt[gte]=2025-01-01&createdAt[lte]=2025-12-31\n" }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Do not rename parameters for different resources:" }) }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: " /api/v1/organizations?status=active\n /api/v1/projects?status=active\n /api/v1/tasks?status=active\n\n /api/v1/organizations?status=active\n /api/v1/projects?state=active // inconsistent parameter name\n /api/v1/tasks?taskStatus=active // overly verbose\n" }) }), "\n", _jsx(_components.h2, { id: "status-code-reference", children: "Status Code Reference" }), "\n", _jsx(_components.p, { children: "Use HTTP status codes to convey the outcome of a request. Consumers rely on these codes to handle responses appropriately." }), "\n", _jsx(_components.h3, { id: "success-codes-2xx", children: "Success Codes (2xx)" }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Code" }), _jsx(_components.th, { children: "Name" }), _jsx(_components.th, { children: "When to Use" }), _jsx(_components.th, { children: "Example" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "200" }) }), _jsx(_components.td, { children: "OK" }), _jsxs(_components.td, { children: ["Standard success for ", _jsx(_components.code, { children: "GET" }), ", ", _jsx(_components.code, { children: "PATCH" }), ", or custom actions that update existing resources"] }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "GET /users/123" }), " returns user data"] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "201" }) }), _jsx(_components.td, { children: "Created" }), _jsx(_components.td, { children: "A new resource was created" }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "POST /users" }), " returns the new user"] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "204" }) }), _jsx(_components.td, { children: "No Content" }), _jsx(_components.td, { children: "The request succeeded but there is no response body" }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "DELETE /users/123" }), " returns empty"] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "202" }) }), _jsx(_components.td, { children: "Accepted" }), _jsx(_components.td, { children: "The request was accepted for processing but is not complete" }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "POST /reports/generate" }), " returns a job ID"] })] })] })] }), "\n", _jsx(_components.h3, { id: "client-error-codes-4xx", children: "Client Error Codes (4xx)" }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Code" }), _jsx(_components.th, { children: "Name" }), _jsx(_components.th, { children: "When to Use" }), _jsx(_components.th, { children: "Example" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "400" }) }), _jsx(_components.td, { children: "Bad Request" }), _jsx(_components.td, { children: "The request is malformed or contains invalid parameters" }), _jsx(_components.td, { children: "Missing required field, invalid enum value" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "401" }) }), _jsx(_components.td, { children: "Unauthorized" }), _jsx(_components.td, { children: "Authentication is required or the token is invalid" }), _jsxs(_components.td, { children: ["Missing ", _jsx(_components.code, { children: "Authorization" }), " header"] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "403" }) }), _jsx(_components.td, { children: "Forbidden" }), _jsx(_components.td, { children: "The user is authenticated but lacks permission" }), _jsx(_components.td, { children: "User tries to delete an organization they do not own" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "404" }) }), _jsx(_components.td, { children: "Not Found" }), _jsx(_components.td, { children: "The requested resource does not exist or the user lacks access" }), _jsxs(_components.td, { children: [_jsx(_components.code, { children: "GET /users/999" }), " where user 999 does not exist"] })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "409" }) }), _jsx(_components.td, { children: "Conflict" }), _jsx(_components.td, { children: "The request conflicts with the current state of the resource" }), _jsx(_components.td, { children: "Creating a user with an email that already exists" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "422" }) }), _jsx(_components.td, { children: "Unprocessable Entity" }), _jsx(_components.td, { children: "The request is well-formed but contains semantic errors" }), _jsx(_components.td, { children: "Validation failed: name too short" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "429" }) }), _jsx(_components.td, { children: "Too Many Requests" }), _jsx(_components.td, { children: "The client has exceeded rate limits" }), _jsx(_components.td, { children: "Client sends 100 requests per second when limit is 10" })] })] })] }), "\n", _jsx(_components.h3, { id: "server-error-codes-5xx", children: "Server Error Codes (5xx)" }), "\n", _jsxs(_components.table, { children: [_jsx(_components.thead, { children: _jsxs(_components.tr, { children: [_jsx(_components.th, { children: "Code" }), _jsx(_components.th, { children: "Name" }), _jsx(_components.th, { children: "When to Use" }), _jsx(_components.th, { children: "Example" })] }) }), _jsxs(_components.tbody, { children: [_jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "500" }) }), _jsx(_components.td, { children: "Internal Server Error" }), _jsx(_components.td, { children: "An unexpected error occurred on the server" }), _jsx(_components.td, { children: "Database connection failed, unhandled exception" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "502" }) }), _jsx(_components.td, { children: "Bad Gateway" }), _jsx(_components.td, { children: "The server received an invalid response from an upstream service" }), _jsx(_components.td, { children: "API gateway cannot reach the application server" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "503" }) }), _jsx(_components.td, { children: "Service Unavailable" }), _jsx(_components.td, { children: "The server is temporarily unable to handle requests" }), _jsx(_components.td, { children: "Maintenance mode, database overload" })] }), _jsxs(_components.tr, { children: [_jsx(_components.td, { children: _jsx(_components.code, { children: "504" }) }), _jsx(_components.td, { children: "Gateway Timeout" }), _jsx(_components.td, { children: "The server did not receive a timely response from an upstream service" }), _jsx(_components.td, { children: "Upstream service took too long to respond" })] })] })] }), "\n", _jsx(_components.h3, { id: "important-guidelines", children: "Important Guidelines" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "List endpoints never return 404 for empty results:" }), " If a list query matches zero resources, return ", _jsx(_components.code, { children: "200 OK" }), " with an empty ", _jsx(_components.code, { children: "data" }), " array. ", _jsx(_components.code, { children: "404" }), " is only for when a specific resource ID does not exist."] }), "\n"] }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: ["GET /api/v1/organizations?status=archived ", _jsx(_components.span, { className: "hljs-comment", children: "// No archived orgs" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"data\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "[" }), _jsx(_components.span, { className: "hljs-punctuation", children: "]" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"pagination\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"total\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "0" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"page\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "1" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"limit\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "20" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"totalPages\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-number", children: "0" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\nGET /api/v1/organizations?status=archived ", _jsx(_components.span, { className: "hljs-comment", children: "// Incorrect: 404 for empty list" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"No organizations found\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsxs(_components.ol, { start: "2", children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Use 404 for missing resources, not permission errors:" }), " Return ", _jsx(_components.code, { children: "404" }), " when a resource does not exist OR when the user lacks permission to access it. This prevents information leakage."] }), "\n"] }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: ["GET /api/v1/organizations/", _jsx(_components.span, { className: "hljs-number", children: "999" }), " ", _jsx(_components.span, { className: "hljs-comment", children: "// User lacks access" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Organization not found\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"RESOURCE_NOT_FOUND\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\nGET /api/v1/organizations/", _jsx(_components.span, { className: "hljs-number", children: "999" }), " ", _jsx(_components.span, { className: "hljs-comment", children: "// Incorrect: reveals resource exists" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"You do not have permission to access this organization\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"PERMISSION_DENIED\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsxs(_components.ol, { start: "3", children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Include error details for 400 and 422:" }), " Help consumers fix validation errors by including field-specific messages."] }), "\n"] }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Validation failed\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"details\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "[" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"field\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"email\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"message\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Invalid email format\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"field\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"password\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"message\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Password must be at least 8 characters\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "]" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsxs(_components.ol, { start: "4", children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Do not expose internal errors to clients:" }), " For ", _jsx(_components.code, { children: "500" }), " errors, return a generic message. Log the full error server-side for debugging."] }), "\n"] }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Internal server error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"INTERNAL_ERROR\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Database connection failed: ECONNREFUSED 127.0.0.1:5432\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.h2, { id: "best-practices-for-api-design", children: "Best Practices for API Design" }), "\n", _jsx(_components.h3, { id: "provide-interactive-documentation", children: "Provide Interactive Documentation" }), "\n", _jsx(_components.p, { children: "Documentation is not optional. Consumers cannot integrate your API if they do not know how it works." }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Use OpenAPI/Swagger:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Define your API contract in YAML or JSON using the OpenAPI Specification." }), "\n", _jsx(_components.li, { children: "Generate interactive documentation with Swagger UI or Redoc." }), "\n", _jsx(_components.li, { children: "Allow consumers to test endpoints directly from the documentation." }), "\n", _jsx(_components.li, { children: "Auto-generate client SDKs in multiple languages." }), "\n"] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Example OpenAPI snippet:" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-yaml", children: [_jsx(_components.span, { className: "hljs-attr", children: "paths:" }), "\n ", _jsx(_components.span, { className: "hljs-string", children: "/organizations:" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "post:" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "summary:" }), " ", _jsx(_components.span, { className: "hljs-string", children: "Create" }), " ", _jsx(_components.span, { className: "hljs-string", children: "a" }), " ", _jsx(_components.span, { className: "hljs-string", children: "new" }), " ", _jsx(_components.span, { className: "hljs-string", children: "organization" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "operationId:" }), " ", _jsx(_components.span, { className: "hljs-string", children: "createOrganization" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "tags:" }), "\n ", _jsx(_components.span, { className: "hljs-bullet", children: "-" }), " ", _jsx(_components.span, { className: "hljs-string", children: "Organizations" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "security:" }), "\n ", _jsx(_components.span, { className: "hljs-bullet", children: "-" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "BearerAuth:" }), " []\n ", _jsx(_components.span, { className: "hljs-attr", children: "requestBody:" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "required:" }), " ", _jsx(_components.span, { className: "hljs-literal", children: "true" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "content:" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "application/json:" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "schema:" }), "\n ", _jsx(_components.span, { className: "hljs-string", children: "$ref:" }), " ", _jsx(_components.span, { className: "hljs-string", children: "'#/components/schemas/CreateOrganizationRequest'" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "responses:" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "'201':" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "description:" }), " ", _jsx(_components.span, { className: "hljs-string", children: "Organization" }), " ", _jsx(_components.span, { className: "hljs-string", children: "created" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "content:" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "application/json:" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "schema:" }), "\n ", _jsx(_components.span, { className: "hljs-string", children: "$ref:" }), " ", _jsx(_components.span, { className: "hljs-string", children: "'#/components/schemas/Organization'" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "'400':" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "description:" }), " ", _jsx(_components.span, { className: "hljs-string", children: "Validation" }), " ", _jsx(_components.span, { className: "hljs-string", children: "failed" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "content:" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "application/json:" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "schema:" }), "\n ", _jsx(_components.span, { className: "hljs-string", children: "$ref:" }), " ", _jsx(_components.span, { className: "hljs-string", children: "'#/components/schemas/ValidationError'" }), "\n"] }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Keep documentation in sync:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Store your OpenAPI spec in version control alongside your code." }), "\n", _jsx(_components.li, { children: "Use code generation or validation tools to ensure your implementation matches the spec." }), "\n", _jsx(_components.li, { children: "Update the spec before deploying changes to production." }), "\n"] }), "\n", _jsx(_components.h3, { id: "make-apis-intuitive-and-consistent", children: "Make APIs Intuitive and Consistent" }), "\n", _jsx(_components.p, { children: "Consumers form expectations based on your first endpoint. Meet those expectations everywhere." }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Guidelines:" }) }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Follow REST conventions:" }), " Use standard HTTP methods, status codes, and URL patterns unless you have a compelling reason to deviate."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Be predictable:" }), " If ", _jsx(_components.code, { children: "GET /organizations" }), " returns a paginated list, then ", _jsx(_components.code, { children: "GET /projects" }), " should also return a paginated list with the same structure."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Use consistent naming:" }), " If you use ", _jsx(_components.code, { children: "camelCase" }), " for JSON fields in one endpoint, use it everywhere. If you use ", _jsx(_components.code, { children: "sortBy" }), " for sorting in one list endpoint, use it in all list endpoints."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Document deviations:" }), " If you must deviate from conventions (e.g., using ", _jsx(_components.code, { children: "PUT" }), " for partial updates), document the reason clearly."] }), "\n"] }), "\n"] }), "\n", _jsx(_components.h3, { id: "provide-sane-defaults", children: "Provide Sane Defaults" }), "\n", _jsx(_components.p, { children: "Do not force consumers to send obvious parameters. Provide sensible defaults that cover the common case." }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Examples:" }) }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-javascript", children: [_jsx(_components.span, { className: "hljs-comment", children: "// Pagination defaults" }), "\n", _jsx(_components.span, { className: "hljs-keyword", children: "if" }), " (!req.", _jsx(_components.span, { className: "hljs-property", children: "query" }), ".", _jsx(_components.span, { className: "hljs-property", children: "page" }), ") req.", _jsx(_components.span, { className: "hljs-property", children: "query" }), ".", _jsx(_components.span, { className: "hljs-property", children: "page" }), " = ", _jsx(_components.span, { className: "hljs-number", children: "1" }), ";\n", _jsx(_components.span, { className: "hljs-keyword", children: "if" }), " (!req.", _jsx(_components.span, { className: "hljs-property", children: "query" }), ".", _jsx(_components.span, { className: "hljs-property", children: "limit" }), ") req.", _jsx(_components.span, { className: "hljs-property", children: "query" }), ".", _jsx(_components.span, { className: "hljs-property", children: "limit" }), " = ", _jsx(_components.span, { className: "hljs-number", children: "20" }), ";\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// Sorting defaults" }), "\n", _jsx(_components.span, { className: "hljs-keyword", children: "if" }), " (!req.", _jsx(_components.span, { className: "hljs-property", children: "query" }), ".", _jsx(_components.span, { className: "hljs-property", children: "sortBy" }), ") req.", _jsx(_components.span, { className: "hljs-property", children: "query" }), ".", _jsx(_components.span, { className: "hljs-property", children: "sortBy" }), " = ", _jsx(_components.span, { className: "hljs-string", children: "'createdAt'" }), ";\n", _jsx(_components.span, { className: "hljs-keyword", children: "if" }), " (!req.", _jsx(_components.span, { className: "hljs-property", children: "query" }), ".", _jsx(_components.span, { className: "hljs-property", children: "sortOrder" }), ") req.", _jsx(_components.span, { className: "hljs-property", children: "query" }), ".", _jsx(_components.span, { className: "hljs-property", children: "sortOrder" }), " = ", _jsx(_components.span, { className: "hljs-string", children: "'descending'" }), ";\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// Status default for create" }), "\n", _jsx(_components.span, { className: "hljs-keyword", children: "if" }), " (!req.", _jsx(_components.span, { className: "hljs-property", children: "body" }), ".", _jsx(_components.span, { className: "hljs-property", children: "status" }), ") req.", _jsx(_components.span, { className: "hljs-property", children: "body" }), ".", _jsx(_components.span, { className: "hljs-property", children: "status" }), " = ", _jsx(_components.span, { className: "hljs-string", children: "'active'" }), ";\n"] }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Benefits:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Simpler client code: Consumers do not need to send parameters for the common case." }), "\n", _jsx(_components.li, { children: "Better user experience: APIs work out of the box without configuration." }), "\n", _jsx(_components.li, { children: "Reduced errors: Fewer required parameters means fewer validation errors." }), "\n"] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Caveat:" }), " Do not hide important behavior behind defaults. If a parameter significantly changes the response (e.g., ", _jsx(_components.code, { children: "include=comments" }), "), document it clearly even if it has a default."] }), "\n", _jsx(_components.h3, { id: "avoid-abbreviations", children: "Avoid Abbreviations" }), "\n", _jsx(_components.p, { children: "Clarity beats brevity. Consumers should not need to guess what your fields mean." }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [" ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"description\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Details about the project\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"createdAt\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T10:30:00Z\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"desc\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Details about the project\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"created\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T10:30:00Z\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"dsc\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Details about the project\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"created_at\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"2025-06-01T10:30:00Z\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Why avoid abbreviations?" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: ["Ambiguity: ", _jsx(_components.code, { children: "desc" }), " could mean \"description\" or \"descending\"."] }), "\n", _jsx(_components.li, { children: "Onboarding: New consumers spend time deciphering your field names." }), "\n", _jsx(_components.li, { children: "Maintenance: Abbreviations are harder to search and refactor." }), "\n"] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Exception:" }), " Well-known abbreviations that are part of the domain (e.g., ", _jsx(_components.code, { children: "id" }), " for identifier, ", _jsx(_components.code, { children: "url" }), " for uniform resource locator) are acceptable."] }), "\n", _jsx(_components.h3, { id: "design-before-you-code", children: "Design Before You Code" }), "\n", _jsx(_components.p, { children: "Spend time designing your API interface before writing implementation code." }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Benefits:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Catch design flaws early: It is cheaper to change a JSON schema in a document than in production code." }), "\n", _jsx(_components.li, { children: "Align stakeholders: Product, frontend, and backend teams can review and agree on the API contract before implementation." }), "\n", _jsx(_components.li, { children: "Generate documentation: Your design document becomes the foundation for your API docs." }), "\n"] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Process:" }) }), "\n", _jsxs(_components.ol, { children: ["\n", _jsx(_components.li, { children: "Sketch endpoints in Insomnia, Postman, or Stoplight." }), "\n", _jsx(_components.li, { children: "Define request/response schemas for each endpoint." }), "\n", _jsx(_components.li, { children: "Review with frontend engineers and product managers." }), "\n", _jsx(_components.li, { children: "Iterate on the design based on feedback." }), "\n", _jsx(_components.li, { children: "Implement the API to match the design." }), "\n", _jsx(_components.li, { children: "Generate documentation from the design." }), "\n"] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Tooling:" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Insomnia/Postman:" }), " Design and test endpoints interactively."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Stoplight Studio:" }), " Visual OpenAPI editor with collaboration features."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "openapi-generator:" }), " Generate server stubs and client SDKs from your OpenAPI spec."] }), "\n"] }), "\n", _jsx(_components.h2, { id: "common-pitfalls-and-how-to-avoid-them", children: "Common Pitfalls and How to Avoid Them" }), "\n", _jsx(_components.h3, { id: "pitfall-1-inconsistent-error-formats", children: "Pitfall 1: Inconsistent Error Formats" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Problem:" }), " Different endpoints return errors in different formats, forcing consumers to write custom parsing logic for each endpoint."] }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-comment", children: "// Endpoint A" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Invalid email\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// Endpoint B" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"message\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Email format is invalid\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"field\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"email\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// Endpoint C" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"errors\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "[" }), _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"INVALID_EMAIL\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"path\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"email\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), _jsx(_components.span, { className: "hljs-punctuation", children: "]" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Solution:" }), " Define a standard error format and use it everywhere."] }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Validation failed\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"VALIDATION_ERROR\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"details\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "[" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"field\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"email\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), " ", _jsx(_components.span, { className: "hljs-attr", children: "\"message\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Invalid email format\"" }), " ", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n ", _jsx(_components.span, { className: "hljs-punctuation", children: "]" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.h3, { id: "pitfall-2-leaking-internal-details", children: "Pitfall 2: Leaking Internal Details" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Problem:" }), " Error messages or response fields expose implementation details that should remain internal."] }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-comment", children: "// Bad: Exposes database schema" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Duplicate entry 'alice@example.com' for key 'users.email_unique'\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"sql\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"INSERT INTO users (email) VALUES ('alice@example.com')\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n\n", _jsx(_components.span, { className: "hljs-comment", children: "// Bad: Exposes file paths" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"File not found: /var/www/uploads/avatar.jpg\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Solution:" }), " Return user-friendly messages. Log internal details server-side."] }), "\n", _jsx(_components.pre, { children: _jsxs(_components.code, { className: "hljs language-json", children: [_jsx(_components.span, { className: "hljs-punctuation", children: "{" }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"error\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"Email already exists\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"code\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"RESOURCE_CONFLICT\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: "," }), "\n ", _jsx(_components.span, { className: "hljs-attr", children: "\"field\"" }), _jsx(_components.span, { className: "hljs-punctuation", children: ":" }), " ", _jsx(_components.span, { className: "hljs-string", children: "\"email\"" }), "\n", _jsx(_components.span, { className: "hljs-punctuation", children: "}" }), "\n"] }) }), "\n", _jsx(_components.h3, { id: "pitfall-3-over-nesting-resources", children: "Pitfall 3: Over-Nesting Resources" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Problem:" }), " Deeply nested paths become hard to work with and maintain."] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: " /api/v1/organizations/123/projects/456/tasks/789/comments/101/replies/202\n" }) }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Solution:" }), " Flatten the path and use query parameters for filtering."] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: " /api/v1/tasks/789/comments/101/replies\n /api/v1/replies?commentId=101&taskId=789\n" }) }), "\n", _jsx(_components.h3, { id: "pitfall-4-ignoring-versioning", children: "Pitfall 4: Ignoring Versioning" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Problem:" }), " Making breaking changes to your API without versioning breaks existing consumers."] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Solution:" }), " Include the version in the URL and follow semantic versioning principles."] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { children: " /api/v1/organizations\n /api/v2/organizations // New version with breaking changes\n" }) }), "\n", _jsx(_components.h3, { id: "pitfall-5-not-testing-edge-cases", children: "Pitfall 5: Not Testing Edge Cases" }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Problem:" }), " APIs work for the happy path but fail for edge cases (empty results, invalid input, concurrent requests)."] }), "\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Solution:" }), " Write comprehensive tests for:"] }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Validation errors" }), "\n", _jsx(_components.li, { children: "Authentication and authorization failures" }), "\n", _jsx(_components.li, { children: "Empty result sets" }), "\n", _jsx(_components.li, { children: "Pagination boundaries" }), "\n", _jsx(_components.li, { children: "Rate limiting" }), "\n", _jsx(_components.li, { children: "Concurrent modifications" }), "\n"] }), "\n", _jsx(_components.h2, { id: "conclusion", children: "Conclusion" }), "\n", _jsx(_components.p, { children: "API design is a skill that improves with practice. The patterns in this guide are not rules to follow blindly. They are tools to help you build APIs that are intuitive, consistent, and maintainable." }), "\n", _jsx(_components.p, { children: "Key takeaways:" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Start with the consumer experience:" }), " Design your API interface before writing code. Use tools like Insomnia or OpenAPI to prototype and document."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Follow REST conventions:" }), " Use standard HTTP methods, status codes, and URL patterns. Deviate only when necessary, and document your reasons."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Be consistent:" }), " Apply the same naming conventions, response structures, and error formats across all endpoints. Consistency reduces cognitive load for consumers."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Provide sane defaults:" }), " Make your APIs work out of the box. Do not force consumers to send obvious parameters."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Document thoroughly:" }), " Interactive documentation is not optional. Use OpenAPI/Swagger to generate docs that stay in sync with your code."] }), "\n"] }), "\n", _jsxs(_components.li, { children: ["\n", _jsxs(_components.p, { children: [_jsx(_components.strong, { children: "Design for evolution:" }), " Version your APIs. Plan for breaking changes. Make it easy for consumers to migrate."] }), "\n"] }), "\n"] }), "\n", _jsx(_components.p, { children: "When your APIs are well-designed, everyone wins:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: "Frontend engineers integrate faster with fewer support tickets." }), "\n", _jsx(_components.li, { children: "Third-party developers adopt your platform more readily." }), "\n", _jsx(_components.li, { children: "Your backend team spends less time fixing misunderstandings and more time building features." }), "\n", _jsx(_components.li, { children: "Your system scales gracefully as requirements evolve." }), "\n"] }), "\n", _jsx(_components.p, { children: "Invest in API design. Your future self and your consumers will thank you." }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, {}) })] }); } function MDXContent(props = {}) { const {wrapper: MDXLayout} = { ..._provideComponents(), ...props.components }; return MDXLayout ? _jsx(MDXLayout, { ...props, children: _jsx(_createMdxContent, { ...props }) }) : _createMdxContent(props); } return { default: MDXContent };