{"id":21,"date":"2026-03-27T08:33:16","date_gmt":"2026-03-27T08:33:16","guid":{"rendered":"https:\/\/siewares.com\/?p=21"},"modified":"2026-03-27T08:33:16","modified_gmt":"2026-03-27T08:33:16","slug":"six-iterations-to-a-type-safe-api-layer-in-typescript","status":"publish","type":"post","link":"https:\/\/siewares.com\/?p=21","title":{"rendered":"Six Iterations to a Type-Safe API Layer in TypeScript"},"content":{"rendered":"\n

We thought <\/em>implements<\/em><\/code> was enough. It wasn’t\u200a\u2014\u200ahere’s the journey from naive to production-ready.<\/em><\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

When your frontend talks to a backend API, you typically create a service layer that mirrors the backend\u2019s interface. This layer acts as a typed contract between your frontend code and the actual HTTP \/ RPC whatever calls\u200a\u2014\u200aand when done right, it catches mismatches at compile time instead of at runtime in production.<\/p>\n\n\n\n

Getting this abstraction right is harder than it looks. We went through six iterations, each fixing a real problem introduced by the previous approach. Here\u2019s what we learned.<\/p>\n\n\n\n

\n\n\n\n

The Problem<\/h3>\n\n\n\n

Say your backend exposes this API:<\/p>\n\n\n\n

interface MyInterface {\n  get(_query: { id: number }): Promise<number>;\n  delete(_query: { id: number }): void;\n}<\/code><\/pre>\n\n\n\n
On the frontend, you want service classes that implement some<\/em> of these methods. The challenge: TypeScript should enforce the contract without forcing you to implement methods you don\u2019t need\u200a\u2014\u200awhile also preventing you from accidentally drifting away from the actual API shape.<\/p>\n\n\n\n
\n\n\n\n
Iteration 1: Plain `implements` \u2014 All or Nothing<\/h3>\n\n\n\n
class MyImpl implements MyInterface {\n  get(_query: { id: number }): Promise<number> {\n    throw new Error('Method not implemented.');\n  }\n  delete(_query: { id: number }): void {\n    throw new Error('Method not implemented.');\n  }\n}<\/code><\/pre>\n\n\n\n
The good:<\/strong> TypeScript fully enforces the contract. If the backend adds a method, compilation fails until you add it too.<\/p>\n\n\n\n
The bad:<\/strong> You must implement everything<\/em>, even if your use case only needs get<\/code>. In a large API with dozens of methods, this becomes noise. Stub methods that throw at runtime are misleading and inflate your codebase.<\/p>\n\n\n\n
=> The obvious fix: skip methods we don’t need. Enter\u00a0Omit<\/code>.<\/p>\n\n\n\n
\n\n\n\n
Iteration 2:\u00a0Omit<\/code>\u00a0\u2014 Explicitly Excluding Methods<\/h3>\n\n\n\n
class MyImplOmit implements Omit<MyInterface, 'delete'> {\n  get(_query: { id: number }): Promise<number> {\n    throw new Error('Method not implemented.');\n  }\n}<\/code><\/pre>\n\n\n\n
The good:<\/strong> You only implement what you need. Clean and minimal.<\/p>\n\n\n\n
The bad:<\/strong> You’re maintaining a negative<\/em> list. Every time the backend adds a method, you must add it to the Omit<\/code> list \u2014 or TypeScript will force you to implement it. The exclusion list grows with the API. You’re fighting against the interface instead of working with it.<\/p>\n\n\n\n
=> Let’s flip the approach: list what we\u00a0want<\/em>\u00a0instead of what we don’t.<\/p>\n\n\n\n
\n\n\n\n
Iteration 3:\u00a0Pick<\/code>\u00a0\u2014 Explicitly Including Methods<\/h2>\n\n\n\n
class MyImplPick implements Pick<MyInterface, 'get'> {\n  get(_query: { id: number }): Promise<number> {\n    throw new Error('Method not implemented.');\n  }\n\n  \/\/ !! Wrong signature \u2014 TypeScript won't catch this\n  delete(_query: { name: string }): void {\n    throw new Error('Method not implemented.');\n  }\n}<\/code><\/pre>\n\n\n\n
The good:<\/strong> You declare exactly which methods you’re implementing. New backend methods don’t break anything.<\/p>\n\n\n\n
The bad:<\/strong> You maintain a string literal union ('get'<\/code>) that mirrors the method names you implement \u2014 duplication that can drift. And critically: since delete<\/code> is not part of the Pick<\/code>, you can add it with a completely wrong signature<\/em> ({ name: string }<\/code> instead of { id: number }<\/code>) and TypeScript won’t complain. The contract is only enforced for picked methods; everything else is unguarded.<\/p>\n\n\n\n
=> Ideally, TypeScript would infer which methods we’re implementing \u2014 without us maintaining a list at all.<\/p>\n\n\n\n
\n\n\n\n
Iteration 4:\u00a0Partial<\/code>\u00a0\u2014 Opt-In Methods With No Duplication<\/h2>\n\n\n\n
class MyImplPartial implements Partial<MyInterface> {\n  get(_query: { id: number }): Promise<number> {\n    throw new Error('Method not implemented.');\n  }\n\n  \/\/ !! Compile error \u2014 wrong signature is caught!\n  \/\/ delete(_query: { name: string }): void { ... }\n\n  \/\/ !! Allowed \u2014 extra method not in the interface\n  newMethodOutsideBackendApi(): void {\n    throw new Error('Method not implemented.');\n  }\n}<\/code><\/pre>\n\n\n\n
The good:<\/strong> No explicit list needed. You implement what you want. Unlike Pick<\/code>, if you do<\/em> implement delete<\/code>, TypeScript enforces the correct signature \u2014 a wrong parameter type like { name: string }<\/code> instead of { id: number }<\/code> will fail compilation. New backend methods don’t break the build either.<\/p>\n\n\n\n
The bad:<\/strong> You can add arbitrary extra methods that have nothing to do with the backend API. Nothing stops a developer from adding newMethodOutsideBackendApi()<\/code> that doesn’t exist on the backend. Your service layer quietly drifts away from the actual contract.<\/p>\n\n\n\n
=> We need the flexibility of\u00a0Partial<\/code>\u00a0with one addition: locking the class down to only methods from the interface.<\/p>\n\n\n\n
\n\n\n\n
Iteration 5:\u00a0Exact<\/code>\u00a0\u2014 Preventing Extra Methods<\/h2>\n\n\n\n
type Exact<T extends U, U> = T & Record<Exclude<keyof T, keyof U>, never>;\n\nclass MyImplExact implements Exact<MyImplExact, Partial<MyInterface>> {\n  get(_query: { id: number }): Promise<number> {\n    throw new Error('Method not implemented.');\n  }\n\n  \/\/ !! Additional parameter \u2014 TypeScript doesn't catch this\n  delete(_query: { id: number; name: string }): void {\n    throw new Error('Method not implemented.');\n  }\n\n  \/\/ Extra methods are blocked \u2014 good!\n  \/\/ newMethodOutsideBackendApi() { ... } \/\/ \u2190 compile error\n}<\/code><\/pre>\n\n\n\n
The good:<\/strong> Extra methods are now forbidden. The Exact<\/code> type maps any key that doesn’t exist in Partial<MyInterface><\/code> to never<\/code>, causing a type error if you try to add one.<\/p>\n\n\n\n
The bad:<\/strong> The parameter check is too loose. delete<\/code> accepts { id: number; name: string }<\/code> \u2014 a superset of the backend’s { id: number }<\/code>. Why doesn’t TypeScript complain? Because of how function parameter compatibility works: a function accepting { id, name }<\/code> can safely substitute for one accepting just { id }<\/code> (the extra property is ignored). Structurally sound \u2014 but in practice, your implementation silently expects data the backend never sends.<\/p>\n\n\n\n
=> One gap remains: enforcing exact parameter matching.<\/p>\n\n\n\n
\n\n\n\n
Iteration 6:\u00a0ApiSubset<\/code>\u00a0\u2014 Full Signature Enforcement<\/h2>\n\n\n\n
type ApiSubset<Impl, Base> = {\n  [K in keyof Impl]: K extends keyof Base\n    ? Impl[K] extends (...args: infer ImplArgs) => any\n      ? Base[K] extends (...args: infer BaseArgs) => infer BaseReturn\n        ? ImplArgs extends BaseArgs\n          ? BaseArgs extends ImplArgs\n            ? (...args: BaseArgs) => BaseReturn\n            : never \/\/ Parameter mismatch\n          : never \/\/ Parameter mismatch\n        : Impl[K]\n      : Impl[K]\n    : never; \/\/ Extra methods not allowed\n};\n\nclass MyImplApiSubset implements ApiSubset<MyImplApiSubset, MyInterface> {\n  get(_query: { id: number }): Promise<number> {\n    throw new Error('Method not implemented.');\n  }\n\n  delete(_query: { id: number }): void {\n    throw new Error('Method not implemented.');\n  }\n\n  \/\/ newMethodOutsideBackendApi() { ... } \/\/ \u2190 compile error\n}<\/code><\/pre>\n\n\n\n
The good:<\/strong> This is the most complete solution. Breaking it down:<\/p>\n\n\n\n
    \n
  • [K in keyof Impl]<\/code>\u00a0\u2014 iterates over every key the class defines<\/li>\n\n\n\n
  • K extends keyof Base<\/code>\u00a0\u2014 if the key exists in the backend interface, enforce the signature; otherwise map it to\u00a0never<\/code>\u00a0(blocking extra methods)<\/li>\n\n\n\n
  • ImplArgs extends BaseArgs<\/code>\u00a0and<\/strong>\u00a0BaseArgs extends ImplArgs<\/code>\u00a0\u2014 bidirectional check ensures parameters are\u00a0exactly<\/em>\u00a0the same, not just compatible in one direction<\/li>\n\n\n\n
  • (...args: BaseArgs) => BaseReturn<\/code>\u00a0\u2014 the return type is inferred from the base interface, keeping the contract authoritative<\/li>\n<\/ul>\n\n\n\n
    Remaining trade-off:<\/strong> The type is self-referential (ApiSubset<MyImplApiSubset, MyInterface><\/code>), which takes a moment to get used to. And because it relies on conditional type inference over function parameters, some edge cases around overloads or complex generics may still slip through.<\/p>\n\n\n\n
    \n\n\n\n
    The Trade-Off Matrix<\/h2>\n\n\n\n
    \"\"<\/figure>\n\n\n\n
    Only\u00a0ApiSubset<\/code>\u00a0checks all four boxes.<\/p>\n\n\n\n
    \n\n\n\n
    Practical Recommendation<\/h2>\n\n\n\n
    Use ApiSubset<\/code><\/strong>. It’s the only approach that lets you implement only what you need, blocks extra methods, enforces exact parameter signatures, and survives new API methods without breaking the build. Define the type once in a shared utility file and you’re set.<\/p>\n\n\n\n
    The self-referential generic (ApiSubset<MyImpl, MyInterface><\/code>) is a small price for a compile-time guarantee that your frontend service layer is always an exact subset of the backend contract.<\/p>\n\n\n\n
    If your team prefers sticking to built-in utility types, Partial<MyInterface><\/code><\/strong> is a solid fallback \u2014 just be aware that it won’t stop developers from adding methods that don’t exist on the backend.<\/p>\n","protected":false},"excerpt":{"rendered":"
    We thought implements was enough. It wasn’t\u200a\u2014\u200ahere’s the journey from naive to production-ready. When your frontend talks to a backend API, you typically create a service layer that mirrors the backend\u2019s interface. This layer acts as a typed contract between your frontend code and the actual HTTP \/ RPC whatever calls\u200a\u2014\u200aand when done right, it […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-21","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/siewares.com\/index.php?rest_route=\/wp\/v2\/posts\/21","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/siewares.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/siewares.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/siewares.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/siewares.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=21"}],"version-history":[{"count":1,"href":"https:\/\/siewares.com\/index.php?rest_route=\/wp\/v2\/posts\/21\/revisions"}],"predecessor-version":[{"id":24,"href":"https:\/\/siewares.com\/index.php?rest_route=\/wp\/v2\/posts\/21\/revisions\/24"}],"wp:attachment":[{"href":"https:\/\/siewares.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=21"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/siewares.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=21"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/siewares.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=21"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}