6c:T431,// ❌ Weakly typed - documentation via comments (can become stale) interface Order { id: string; // Must be UUID format status: string; // One of: 'pending', 'paid', 'shipped', 'delivered' amount: number; // In cents, not dollars createdAt: string; // ISO 8601 format } // ✅ Strongly typed - documentation IS the code type OrderId = string & { readonly brand: unique symbol }; type MonetaryAmount = { cents: number; currency: Currency }; type ISODateTime = string & { readonly brand: unique symbol }; type OrderStatus = | 'pending_payment' | 'payment_received' | 'processing' | 'shipped' | 'delivered' | 'cancelled'; interface Order { id: OrderId; status: OrderStatus; totalAmount: MonetaryAmount; createdAt: ISODateTime; shippedAt: ISODateTime | null; // Null until shipped } // The type system now documents: // - What format IDs must have // - Exactly which statuses are valid // - That amounts are in cents with explicit currency // - That shippedAt is nullable (not yet shipped)6d:T44b,// ❌ Signature hides behavior - what can go wrong? What do I get back? async function getUser(id: string): Promise; // ✅ Signature reveals behavior explicitly async function getUserById( userId: UserId ): Promise; // Null clearly indicates not-found // ❌ Many parameters - hard to remember order, easy to misuse function createOrder( userId: string, items: Item[], address: Address, expedited: boolean, giftWrap: boolean, promoCode: string | null ): Promise; // ✅ Options object - self-documenting at call site interface CreateOrderOptions { userId: UserId; items: OrderItem[]; shippingAddress: Address; shipping: ShippingOption; giftWrapping?: GiftWrapOption; promotionalCode?: PromoCode; } function createOrder(options: CreateOrderOptions): Promise; // Call site is now readable: const order = await createOrder({ userId: currentUser.id, items: cartItems, shippingAddress: savedAddress, shipping: ShippingOption.EXPEDITED, giftWrapping: { message: "Happy Birthday!" }, });6e:T451,// ❌ Returns user or throws - caller must read docs to know exceptions async function authenticate( email: string, password: string ): Promise; // Throws on failure - but which exceptions? // ✅ Return type documents all outcomes type AuthenticationResult = | { success: true; user: User; session: Session } | { success: false; reason: 'invalid_credentials' } | { success: false; reason: 'account_locked'; unlockAt: Date } | { success: false; reason: 'email_not_verified'; resendLink: string } | { success: false; reason: 'mfa_required'; challengeId: string }; async function authenticate( credentials: UserCredentials ): Promise; // Caller handles all cases explicitly: const result = await authenticate(credentials); if (result.success) { return redirect('/dashboard', { session: result.session }); } switch (result.reason) { case 'account_locked': return showLockedMessage(result.unlockAt); case 'mfa_required': return promptForMFA(result.challengeId); // ... TypeScript ensures all cases are handled }6f:T592,// ❌ Flat, unorganized API - hard to discover capabilities interface APIClient { getUser(id: string): User; listOrders(userId: string): Order[]; getProduct(id: string): Product; updateUserEmail(id: string, email: string): void; createOrder(userId: string, items: Item[]): Order; cancelOrder(orderId: string): void; getOrderStatus(orderId: string): Status; // ... 50 more methods at the same level } // ✅ Organized into discoverable domains interface APIClient { readonly users: UserAPI; readonly orders: OrderAPI; readonly products: ProductAPI; readonly inventory: InventoryAPI; } interface UserAPI { getById(id: UserId): Promise; update(id: UserId, changes: UserUpdate): Promise; preferences: UserPreferencesAPI; // Nested for sub-domain } interface OrderAPI { create(options: CreateOrderOptions): Promise; getById(id: OrderId): Promise; listForUser(userId: UserId, filters?: OrderFilters): Promise; // Actions grouped clearly submit(id: OrderId): Promise; cancel(id: OrderId, reason: CancellationReason): Promise; refund(id: OrderId, request: RefundRequest): Promise; } // Usage becomes discoverable through autocomplete: // client.orders. <- IDE shows create, getById, listForUser, submit, cancel, refund // client.orders.create({ ... })70:T4f5,// Establish and follow conventions: // Convention: getXById returns X | null // Convention: getXByIdOrThrow throws NotFoundError // Convention: listX returns X[] (empty if none) // Convention: findX returns X | null (for single-item searches) // Convention: searchX returns SearchResult (with metadata) interface UserRepository { // Single item by ID - may not exist getById(id: UserId): Promise; getByIdOrThrow(id: UserId): Promise; // Throws if not found // Single item by criteria - may not exist findByEmail(email: string): Promise; // Collection - always returns array (empty if none match) listByOrganization(orgId: OrganizationId): Promise; listActive(): Promise; // Search with pagination/metadata search(criteria: UserSearchCriteria): Promise>; } // Once learned, these conventions apply everywhere: interface OrderRepository { getById(id: OrderId): Promise; // Same pattern! getByIdOrThrow(id: OrderId): Promise; findByTrackingNumber(num: string): Promise; listByUser(userId: UserId): Promise; search(criteria: OrderSearchCriteria): Promise>; }71:T79d,// ❌ Unhelpful errors - developer must investigate throw new Error("Invalid parameter"); throw new Error("Operation failed"); throw new Error("Error code: 4012"); // ✅ Self-documenting errors class ValidationError extends Error { constructor( public readonly field: string, public readonly value: unknown, public readonly constraint: string, public readonly suggestion?: string ) { super( `Validation failed for '${field}': ${constraint}. ` + `Received: ${JSON.stringify(value)}. ` + (suggestion ? `Suggestion: ${suggestion}` : '') ); } } // Usage produces helpful message: throw new ValidationError( 'orderItems', [], 'must contain at least one item', 'Add items using order.addItem() before calling submit()' ); // Message: "Validation failed for 'orderItems': must contain at least one item. // Received: []. Suggestion: Add items using order.addItem() before calling submit()" // ❌ Generic permission error throw new Error("Access denied"); // ✅ Self-documenting permission error class PermissionError extends Error { constructor( public readonly action: string, public readonly resource: string, public readonly requiredPermission: string, public readonly userPermissions: string[] ) { super( `Cannot ${action} ${resource}: requires '${requiredPermission}' permission. ` + `Current permissions: [${userPermissions.join(', ')}]. ` + `Contact your administrator to request access.` ); } } throw new PermissionError( 'delete', 'Order #12345', 'orders:delete', ['orders:read', 'orders:create'] ); // Message: "Cannot delete Order #12345: requires 'orders:delete' permission. // Current permissions: [orders:read, orders:create]. // Contact your administrator to request access."65:{"json":{"id":"seed_57f4d4d8ac883c543f7a204f9336cb23","slug":"lld-api-documentation","category":"System Design (LLD)","topic":"API Documentation","title":"API Documentation","description":"Master the discipline of API documentation—from designing self-documenting interfaces that communicate intent through their structure, to leveraging tools like OpenAPI and Swagger, to establishing best practices that keep documentation accurate, complete, and maintainable as APIs evolve.","difficulty":"INTERMEDIATE","estimatedMinutes":60,"pages":[{"id":"seed_70f471c3badfdd26752eb8f2c5ff92f9","title":"Self-Documenting APIs","order":0,"content":[{"id":"opening-hook","title":"The Documentation That Writes Itself","content":[{"data":{"content":"Every API tells a story. The question is: **Does your API tell its story clearly, or does it mumble incoherently, forcing developers to guess at its meaning?**\n\nThe best APIs are those where reading the code is reading the documentation. Method names explain *what* happens. Parameter types constrain *what's valid*. Return types promise *what you'll receive*. Error types enumerate *what can go wrong*. The API surface itself becomes a contract so precise that external documentation serves only to elaborate on edge cases and provide examples—not to explain fundamentals.\n\nThis is the ideal of **self-documenting APIs**: interfaces designed with such clarity that their structure communicates their semantics. When APIs achieve this quality, developers experience what feels like intuition—but is actually the result of meticulous design decisions that anticipate questions before they arise."},"type":"text"},{"data":{"icon":"Target","title":"What You Will Learn","content":"By the end of this page, you will understand the principles, techniques, and patterns that make APIs self-documenting. You'll learn how naming, typing, structure, and consistency combine to create interfaces that communicate effortlessly—reducing bugs, accelerating onboarding, and making your APIs a joy to use.","variant":"info"},"type":"callout"}]},{"id":"self-documentation-principle","title":"The Self-Documentation Principle","content":[{"data":{"content":"Self-documentation is not about eliminating all external documentation—it's about ensuring that the API itself is the **primary source of truth**. External documentation elaborates, provides context, and offers examples. But the API's structure should never contradict or be mysterious without consulting a manual.\n\n**The hierarchy of understanding:**\n\n1. **The API surface** — Names, types, and structure should explain 80% of behavior\n2. **Inline documentation** — Comments, docstrings, and annotations clarify nuance\n3. **External documentation** — Tutorials, guides, and reference manuals provide depth\n\nWhen this hierarchy inverts—when developers *must* read external docs to understand basic operations—the API has failed to communicate. Self-documenting APIs succeed when a competent developer, seeing the interface for the first time, can correctly predict its behavior."},"type":"text"},{"data":{"icon":"Lightbulb","title":"The 'Newcomer Test'","content":"Ask a developer unfamiliar with your API to predict what a method does based solely on its signature. If they guess correctly 80% of the time, your API is self-documenting. If they're wrong more often than right, your naming and structure need work.","variant":"tip"},"type":"callout"},{"data":{"content":"**Why self-documentation matters:**\n\n- **Reduced cognitive load** — Developers don't need to remember what they read; the API reminds them\n- **Faster onboarding** — New team members become productive quickly\n- **Fewer bugs** — When behavior is obvious, misuse becomes difficult\n- **Documentation sustainability** — External docs stay accurate because the source of truth is the code\n- **Better discoverability** — IDE autocomplete becomes genuine guidance, not just a list of options"},"type":"text"}],"titleType":"number","titleNumber":1},{"id":"naming-as-documentation","title":"Naming as Documentation","content":[{"data":{"content":"Names are the most visible form of documentation. Every method name, parameter name, class name, and constant name is an opportunity to communicate intent—or to obscure it.\n\n**The principles of self-documenting names:**"},"type":"text"},{"data":{"items":["**Be specific, not generic** — `getUserById(id)` tells more than `getUser(id)`. `sendOrderConfirmationEmail()` beats `notify()`.","**Use domain vocabulary** — If your domain says 'shipment', don't call it 'delivery' in code. Consistency with domain language reduces translation overhead.","**Reveal intent, not implementation** — `cacheUserProfile()` tells *what*, not *how*. Don't expose internal mechanisms in public names.","**Prefer verbs for actions, nouns for entities** — `calculateTax()` is an action. `TaxCalculator` is an entity. Mixing conventions confuses readers.","**Avoid abbreviations unless universally understood** — `getConfig()` is fine; `getUCTxn()` is not. When in doubt, spell it out.","**Include units in numeric names** — `timeoutMs`, `distanceKm`, `weightGrams` prevent unit confusion that causes real bugs."],"title":{"icon":"BookOpen","text":"Naming Principles for API Clarity","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"code":"// ❌ Poor naming - requires external documentation\ninterface DataService {\n get(id: string): Promise; // Get what? From where?\n process(data: object): void; // Process how? What happens?\n update(item: any, flag: boolean): void; // What does the flag mean?\n}\n\n// ✅ Self-documenting naming - intent is clear from names\ninterface UserAccountService {\n getUserById(userId: string): Promise;\n \n deactivateAccount(\n userId: string,\n reason: DeactivationReason\n ): Promise;\n \n updateEmailPreferences(\n userId: string,\n preferences: EmailPreferences\n ): Promise;\n}\n\n// ❌ Confusing parameter names\nfunction send(to: string, subj: string, body: string, flag: boolean);\n\n// ✅ Self-documenting parameters\nfunction sendEmail(\n recipientAddress: string,\n subject: string,\n htmlBody: string,\n sendImmediately: boolean\n): Promise;","title":"Naming: Poor vs Self-Documenting","language":"typescript","showLineNumbers":true},"type":"code"},{"data":{"icon":"AlertCircle","title":"The Boolean Parameter Trap","content":"Boolean parameters are documentation killers. What does `deleteUser(id, true)` mean? Is `true` for soft-delete or hard-delete? Always prefer named enums or options objects over boolean flags. `deleteUser(id, { permanent: true })` or `deleteUser(id, DeletionType.PERMANENT)` is instantly clear.","variant":"warning"},"type":"callout"}],"titleType":"number","titleNumber":2},{"id":"types-as-constraints","title":"Types as Constraints and Documentation","content":[{"data":{"content":"Type systems are documentation mechanisms that the compiler enforces. A well-typed API doesn't just prevent bugs—it communicates what's possible and what's forbidden.\n\n**Using types to document:**\n\n- **Domain primitives over raw types** — `userId: UserId` is more meaningful than `userId: string`\n- **Enums over strings/numbers** — `status: OrderStatus` beats `status: string`\n- **Optionality as specification** — `middleName?: string` documents that middle names are optional\n- **Union types for valid states** — `status: 'pending' | 'approved' | 'rejected'` enumerates possibilities\n- **Branded types for domain concepts** — Prevent mixing conceptually distinct values that share structural types"},"type":"text"},{"data":{"code":"$6c","title":"Types as Living Documentation","language":"typescript","showLineNumbers":true},"type":"code"},{"data":{"content":"**The power of impossible states:**\n\nWell-designed types make illegal states unrepresentable. Instead of runtime checks and documentation warnings, the compiler prevents misuse entirely."},"type":"text"},{"data":{"code":"// ❌ Possible invalid states - requires documentation and runtime checks\ninterface Request {\n type: 'sync' | 'async';\n callback?: () => void; // \"Required if type is 'async'\" - but nothing enforces this!\n timeout?: number; // \"Only valid if type is 'async'\" - again, not enforced\n}\n\n// ✅ Type system enforces valid combinations\ntype SyncRequest = {\n type: 'sync';\n // No callback or timeout - they don't apply\n};\n\ntype AsyncRequest = {\n type: 'async';\n callback: () => void; // Required - not optional\n timeoutMs: number; // Required - with units in name\n};\n\ntype Request = SyncRequest | AsyncRequest;\n\n// Now it's impossible to create an async request without a callback\n// The types ARE the documentation - and they're always accurate","title":"Making Illegal States Unrepresentable","language":"typescript","showLineNumbers":true},"type":"code"},{"data":{"icon":"Info","title":"Types > Comments","content":"Comments can lie—they're not checked by the compiler. Types cannot lie—they're enforced at compile time. Whenever you find yourself writing a comment explaining a constraint, ask: 'Can I encode this in the type system instead?'","variant":"note"},"type":"callout"}],"titleType":"number","titleNumber":3},{"id":"method-signatures-that-speak","title":"Method Signatures That Speak","content":[{"data":{"content":"A method signature is a micro-contract. It promises: *give me these inputs, and I'll give you this output (or this error)*. Self-documenting signatures make this contract explicit and unambiguous.\n\n**Elements of a self-documenting signature:**"},"type":"text"},{"data":{"items":["**Return type precision** — `User | null` vs `User` communicates whether not-found is a valid outcome","**Error typing** — `Result` documents failure modes","**Parameter ordering** — Most important/required parameters first, optional parameters last","**Options objects for complex inputs** — When you have more than 2-3 parameters, group into an options object","**Async indication** — `Promise` signals that the operation is asynchronous","**Mutation indicators** — Methods returning `void` often mutate; those returning new values often don't"],"title":{"icon":"Code","text":"Signature Design Principles","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"code":"$6d","title":"Expressive Method Signatures","language":"typescript","showLineNumbers":true},"type":"code"},{"data":{"content":"**Return types that tell stories:**\n\nThe return type should answer: *What can I expect?* Not just the success case, but all possible outcomes."},"type":"text"},{"data":{"code":"$6e","title":"Comprehensive Return Types","language":"typescript","showLineNumbers":true},"type":"code"}],"titleType":"number","titleNumber":4},{"id":"structural-self-documentation","title":"Structural Self-Documentation","content":[{"data":{"content":"Beyond individual names and types, the *structure* of your API communicates intent. How you organize methods, group related operations, and layer abstractions all contribute to (or detract from) self-documentation.\n\n**Structural elements that document:**"},"type":"text"},{"data":{"items":["**Grouping by entity** — All user operations in `UserService`, all order operations in `OrderService`. Developers know where to look.","**CRUD consistency** — If `createUser`, `updateUser`, `deleteUser` exist, developers expect `getUser`. Consistency enables prediction.","**Action-oriented interfaces** — `OrderProcessor.submitOrder()`, `OrderProcessor.cancelOrder()` groups by operation domain.","**Read vs Write separation (CQRS)** — `UserQueryService` vs `UserCommandService` signals which operations mutate state.","**Fluent interfaces** — `query.where('status', '=', 'active').orderBy('date').limit(10)` reads like a sentence.","**Builder patterns** — `OrderBuilder.withItems(...).withShipping(...).build()` guides construction step-by-step."],"title":{"icon":"Layers","text":"API Structure as Documentation","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"code":"$6f","title":"Self-Documenting API Structure","language":"typescript","showLineNumbers":true},"type":"code"},{"data":{"icon":"Lightbulb","title":"The Autocomplete Test","content":"Type your API client in an IDE and press '.' for autocomplete. Can a developer find what they need without reading docs? If the list is overwhelming or options are unclear, restructure for discoverability.","variant":"tip"},"type":"callout"}],"titleType":"number","titleNumber":5},{"id":"consistent-conventions","title":"Consistent Conventions as Documentation","content":[{"data":{"content":"Consistency is the silent documentation that lets developers transfer knowledge. When an API follows predictable conventions, learning one part teaches you about other parts.\n\n**Essential conventions to maintain:**"},"type":"text"},{"data":{"rows":[["Naming verbs","`get`, `list`, `create`, `update`, `delete`","Developers predict operation type from prefix"],["Async indicators","All async methods return `Promise`","Signature reveals execution model"],["Null handling","`getById` returns `T | null`; `getByIdOrThrow` throws","Return type documents not-found behavior"],["Plural vs singular","`getUser()` vs `listUsers()`","Naming indicates single vs collection"],["Parameter order","Required params first, options object last","Consistent ordering reduces errors"],["Error patterns","All methods throw `DomainError` subclasses","Predictable error hierarchy"],["Pagination","All list methods accept `{ limit, cursor }`","Consistent pattern across endpoints"]],"caption":"Convention Categories for Self-Documenting APIs","headers":["Category","Convention Example","Why It Documents"]},"type":"table"},{"data":{"code":"$70","title":"Consistency Through Naming Conventions","language":"typescript","showLineNumbers":true},"type":"code"},{"data":{"icon":"Info","title":"Document Your Conventions","content":"While individual usages should be self-documenting, the conventions themselves should be documented in a style guide. This meta-documentation helps new developers understand the patterns faster and maintain consistency in their contributions.","variant":"note"},"type":"callout"}],"titleType":"number","titleNumber":6},{"id":"error-messages-documentation","title":"Error Messages as Documentation","content":[{"data":{"content":"Error messages are documentation that appears exactly when developers need it—at the moment of confusion. Great error messages don't just say what went wrong; they explain why, suggest fixes, and link to relevant resources.\n\n**Principles of self-documenting errors:**"},"type":"text"},{"data":{"items":["**What happened** — Specific description of the failure, not generic codes","**Why it happened** — The condition that triggered the error","**What to do** — Actionable guidance for resolution","**Context** — Relevant values that help diagnose the issue","**Documentation link** — URL to detailed docs when appropriate"],"title":{"icon":"AlertCircle","text":"Error Message Quality","type":"icon","color":"destructive","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"code":"$71","title":"Self-Documenting Error Design","language":"typescript","showLineNumbers":true},"type":"code"},{"data":{"icon":"Lightbulb","title":"Test Error Messages","content":"When writing tests, don't just verify that errors are thrown—verify that error messages are helpful. Treat error messages as part of your API's user interface.","variant":"tip"},"type":"callout"}],"titleType":"number","titleNumber":7},{"id":"summary-self-documenting-apis","title":"Summary: Self-Documenting APIs","content":[{"data":{"content":"Self-documenting APIs represent the pinnacle of API craftsmanship. They communicate intent through structure, constrain usage through types, and guide developers through consistent conventions. Let's consolidate the key principles:"},"type":"text"},{"data":{"type":"ordered","items":["**Names are your first documentation layer** — Choose specific, domain-aligned, intention-revealing names for methods, parameters, and types.","**Types enforce and document constraints** — Use the type system to make illegal states unrepresentable rather than documenting restrictions in comments.","**Signatures tell complete stories** — Return types should reveal all possible outcomes, including errors and edge cases.","**Structure aids discoverability** — Organize APIs into logical domains so developers can find capabilities through exploration.","**Consistency enables transfer learning** — Establish and follow conventions so learning one part teaches developers about the whole.","**Error messages are teachable moments** — Design errors to explain, guide, and help developers resolve issues independently."],"title":{"icon":"CheckCircle","text":"Key Takeaways","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"content":"**What's next:**\n\nWhile self-documenting APIs reduce the need for external documentation, they don't eliminate it. Tutorials, examples, and reference guides still add value. The next page explores **Documentation Tools and Formats**—including OpenAPI, Swagger, JSDoc, and other tools that generate, display, and maintain API documentation at scale."},"type":"text"},{"data":{"icon":"CheckCircle","title":"Page Complete","content":"You now understand how to design APIs that communicate their purpose through structure alone. Self-documenting APIs reduce cognitive load, prevent misuse, and make external documentation an enhancement rather than a crutch. Next, we'll explore the tools and formats that complement self-documentation with rich reference materials.","variant":"success"},"type":"callout"}],"titleType":"number","titleNumber":8}],"isLocked":false},{"id":"seed_05704964293292cf5351263b1d6ca4d0","title":"Documentation Tools and Formats","order":1,"content":null,"isLocked":true},{"id":"seed_25686fc180399da40543bea2f4e540fd","title":"Documentation Best Practices","order":2,"content":null,"isLocked":true},{"id":"seed_6d03998765d3f737b568a89870e9b1bc","title":"Keeping Documentation Current","order":3,"content":null,"isLocked":true}]}}