API Documentation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

// ❌ Poor naming - requires external documentation
interface DataService {
    get(id: string): Promise<any>;           // Get what? From where?
    process(data: object): void;              // Process how? What happens?
    update(item: any, flag: boolean): void;   // What does the flag mean?
}
 
// ✅ Self-documenting naming - intent is clear from names
interface UserAccountService {
    getUserById(userId: string): Promise<User | null>;
    
    deactivateAccount(
        userId: string,
        reason: DeactivationReason
    ): Promise<void>;
    
    updateEmailPreferences(
        userId: string,
        preferences: EmailPreferences
    ): Promise<void>;
}
 
// ❌ Confusing parameter names
function send(to: string, subj: string, body: string, flag: boolean);
 
// ✅ Self-documenting parameters
function sendEmail(
    recipientAddress: string,
    subject: string,
    htmlBody: string,
    sendImmediately: boolean
): Promise<EmailReceipt>;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

// ❌ 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)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// ❌ Possible invalid states - requires documentation and runtime checks
interface Request {
    type: 'sync' | 'async';
    callback?: () => void;  // "Required if type is 'async'" - but nothing enforces this!
    timeout?: number;       // "Only valid if type is 'async'" - again, not enforced
}
 
// ✅ Type system enforces valid combinations
type SyncRequest = {
    type: 'sync';
    // No callback or timeout - they don't apply
};
 
type AsyncRequest = {
    type: 'async';
    callback: () => void;   // Required - not optional
    timeoutMs: number;      // Required - with units in name
};
 
type Request = SyncRequest | AsyncRequest;
 
// Now it's impossible to create an async request without a callback
// The types ARE the documentation - and they're always accurate

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

// ❌ Signature hides behavior - what can go wrong? What do I get back?
async function getUser(id: string): Promise<User>;
 
// ✅ Signature reveals behavior explicitly
async function getUserById(
    userId: UserId
): Promise<User | null>;  // 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<Order>;
 
// ✅ 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<OrderResult>;
 
// Call site is now readable:
const order = await createOrder({
    userId: currentUser.id,
    items: cartItems,
    shippingAddress: savedAddress,
    shipping: ShippingOption.EXPEDITED,
    giftWrapping: { message: "Happy Birthday!" },
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// ❌ Returns user or throws - caller must read docs to know exceptions
async function authenticate(
    email: string,
    password: string
): Promise<User>;  // 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<AuthenticationResult>;
 
// 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
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

// ❌ 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<User | null>;
    update(id: UserId, changes: UserUpdate): Promise<User>;
    preferences: UserPreferencesAPI;  // Nested for sub-domain
}
 
interface OrderAPI {
    create(options: CreateOrderOptions): Promise<Order>;
    getById(id: OrderId): Promise<Order | null>;
    listForUser(userId: UserId, filters?: OrderFilters): Promise<Order[]>;
    
    // Actions grouped clearly
    submit(id: OrderId): Promise<SubmitResult>;
    cancel(id: OrderId, reason: CancellationReason): Promise<void>;
    refund(id: OrderId, request: RefundRequest): Promise<RefundResult>;
}
 
// Usage becomes discoverable through autocomplete:
// client.orders.  <- IDE shows create, getById, listForUser, submit, cancel, refund
// client.orders.create({ ... })

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

// 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<X> (with metadata)
 
interface UserRepository {
    // Single item by ID - may not exist
    getById(id: UserId): Promise<User | null>;
    getByIdOrThrow(id: UserId): Promise<User>;  // Throws if not found
    
    // Single item by criteria - may not exist
    findByEmail(email: string): Promise<User | null>;
    
    // Collection - always returns array (empty if none match)
    listByOrganization(orgId: OrganizationId): Promise<User[]>;
    listActive(): Promise<User[]>;
    
    // Search with pagination/metadata
    search(criteria: UserSearchCriteria): Promise<SearchResult<User>>;
}
 
// Once learned, these conventions apply everywhere:
interface OrderRepository {
    getById(id: OrderId): Promise<Order | null>;  // Same pattern!
    getByIdOrThrow(id: OrderId): Promise<Order>;
    findByTrackingNumber(num: string): Promise<Order | null>;
    listByUser(userId: UserId): Promise<Order[]>;
    search(criteria: OrderSearchCriteria): Promise<SearchResult<Order>>;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

// ❌ 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."