DEV Community: Vinícius S. de Pontes

When an SDK Is Better Than Documentation

Vinícius S. de Pontes — Sat, 05 Sep 2026 19:31:23 +0000

When I implemented distributed memoization, using the pattern correctly required more than just calling an API.

A consumer had to check the result store, generate the right key, deserialize the result, handle a cache miss, call the original service, and decide what to do if the cache was unavailable.

I could document all of that.

But then every consumer would have to implement it.

Instead, I created an SDK.

An SDK, or Software Development Kit, is a package that gives developers a simpler interface for interacting with a system or capability. It can wrap APIs, configuration, authentication, retries, data transformations, and other implementation details behind code that is easier to use consistently.

This becomes especially valuable in a microservices architecture, where several independent services may consume the same capability. Without a shared abstraction, small implementation differences can easily spread across the system.

In this case, the SDK wasn't only about code reuse. It turned the expected way of using the architecture into code.

Hiding the integration

Without an SDK, a consumer might end up with something like this:

const key = createResultKey("sales-report", 3, input);

const cachedResult = await resultStore.get(key);

if (cachedResult) {
  return JSON.parse(cachedResult);
}

return reportService.generate(input);

This doesn't look particularly complicated.

The problem appears when five services need to do it.

One might normalize the input differently. Another might forget the function version. One might fail the whole request when the result store is unavailable, while another falls back to the service.

In a microservices system, this is particularly easy to run into. Each service is developed and deployed independently, often by different teams and on different schedules. If every service implements the integration itself, those implementations can slowly diverge.

Even with good documentation, we're still asking every consumer to understand and reproduce the same decisions.

With an SDK, the consumer can see something closer to this:

const report = await reportClient.generateSalesReport(input);

Internally, the SDK handles the result lookup and falls back to the service when necessary.

The consumer doesn't need to know how keys are generated or how the fallback works.

It only needs to know how to generate a report.

Code reuse is only part of the value

Shared functions could also remove some duplication.

An SDK goes a little further because it can define the boundary through which consumers interact with a capability.

For distributed memoization, that meant centralizing things such as:

input normalization and key generation;
serialization and deserialization;
cache lookup behavior;
timeouts and fallback rules;
connection and configuration details.
Authentication and authorization mechanisms

If one of these decisions changes, consumers don't necessarily need to change.

Maybe the key format moves from:

sales-report:v3:{input-hash}

to:

result:sales-report:v4:{input-hash}

That is an implementation detail of the memoization mechanism. It shouldn't become an implementation detail of every service using it.

The SDK creates a place for that knowledge to live.

Making the expected path easier

Documentation describes how something should be used.

An SDK can make that usage the default.

This distinction becomes more useful as an architecture grows.

Suppose ten services need to call the same internal platform. We can give every team documentation explaining authentication, retries, headers, error mapping, timeouts, and endpoint conventions.

Or we can expose:

const client = new PlatformClient(config);

const result = await client.execute(input);

Documentation is still useful. Consumers should understand the important behavior and tradeoffs.

They just shouldn't have to reproduce infrastructure code to use the platform correctly.

This also makes standardization less dependent on people remembering conventions.

If authentication changes, the SDK can change.

If every request should include new telemetry, the SDK can add it.

If a timeout policy needs to be adjusted, there is one implementation instead of several slightly different ones spread across the codebase.

What belongs behind an SDK?

Not every abstraction needs its own package.

A small helper used twice is probably just a small helper.

An SDK becomes more interesting when several consumers interact with the same capability, and there are meaningful rules around that interaction.

Internal APIs are an obvious example, but the same idea can apply to caching, authentication, feature flags, event publishing, storage, business rules engines, or any other shared platform capability.

The important part is finding the right boundary.

An SDK that exposes every internal detail doesn't abstract much. At the other extreme, an SDK that tries to anticipate every possible use case can become more complicated than the system it hides.

A good SDK usually gives consumers the concepts they actually care about while keeping infrastructure decisions underneath.

In the memoization example, the consumer cares about generating the report.

It doesn't care how a deterministic input becomes a cache key.

That difference is a useful place to draw the boundary.

SDKs are therefore more than a way to avoid copying code.

Used at the right boundary, they let us implement an architectural decision once and give consumers a smaller, harder-to-misuse interface to it.

Distributed Memoization: Avoid Repeating Expensive Work

Vinícius S. de Pontes — Fri, 21 Aug 2026 16:08:13 +0000

Some operations produce the same output when given the same input.

Without caching, every request still reaches the service, accesses its dependencies, and performs the same work again. This happens even when the result was calculated moments ago.

I encountered this in a reporting service. The main database query was already accelerated by a materialized view, but every request still had to retrieve, validate, process, and enrich the data.

Caching the final result was faster and cheaper. Instead of optimizing one dependency, we could skip the entire operation.

That experience changed how I think about caching: sometimes the most useful thing to cache is not the data, but the completed work.

This is a form of distributed memoization.

Caching the operation

Traditional caching is often described in terms of database records or query responses.

That helps with data access, but the application may still need to perform the same processing afterward. Distributed memoization looks at the problem differently. It stores the output of an operation.

Consider an operation that generates a sales report:

generateSalesReport({
  companyId: "company-123",
  period: "2026-07",
  currency: "USD"
});

Generating the report may still require retrieving the precomputed data, validating it, applying business rules, enriching it with data from other sources, and formatting the response.

The database query was already fast, but the complete operation still had a cost. If multiple users requested the same report, storing the final result avoided repeating the entire processing pipeline.

The consumer checks a result store first. On a hit, it returns the completed report. On a miss, it calls the original service, which generates and stores the result.

Identifying a result

The result can be stored using a key derived from the operation and its input:

result:sales-report:v3:7f83b165...

A practical key contains:

{operation}:{function-version}:{input-hash}

The function version prevents a new implementation from returning results produced by older code.

The input should be normalized before hashing. Normalization means converting equivalent inputs into a single, consistent representation.

For example, these objects contain the same data:

{"companyId":"company-123","period":"2026-07","currency":"USD"}

{"currency":"USD","period":"2026-07","companyId":"company-123"}

A direct hash of their serialized forms could produce different keys because the fields appear in a different order. Normalization can sort object fields and standardize dates and casing.

After normalization, equivalent inputs produce the same hash and reuse the same stored result.

One possible implementation

The result store could be Valkey, Redis, or another key-value store with suitable latency and expiration support.

In a serverless architecture, the flow might look like this:

The consumer checks Valkey.
On a miss, it calls API Gateway.
API Gateway invokes Lambda.
Lambda reads any required data and calculates the result.
Lambda stores the result in Valkey.
Future requests read it directly.

The same pattern works without serverless components. Lambda could be a service running in a container, a background worker, or an application process. Similarly, the data source could be a database, an external API, a file, an AI model, or another dependency used by the operation.

The important distinction is between the fast path, which returns completed work, and the computation path, which produces results that do not exist yet.

Keeping writes centralized

Consumers only need read access to the result store.

The service responsible for the operation remains the only writer. This prevents consumers from publishing arbitrary results and keeps the calculation logic in one place.

A shared client library can hide the lookup and fallback behavior:

const result = await generateSalesReport(input);

Internally, the library:

Builds the key.
Checks the result store.
Returns the stored value on a hit.
Calls the service on a miss.

It can also handle serialization, timeouts, and fallback consistently across consumers.

Invalidating results

An operation may depend on data that changes over time.

The sales report, for example, may use conversion rates to present transactions in a selected currency. When a rate changes, the application should explicitly invalidate reports calculated with that currency.

async function updateConversionRate(input) {
  const conversionRate =
    await conversionRateRepository.update(input);

  await reportCache.invalidateByCurrency(
    conversionRate.targetCurrency
  );

  return conversionRate;
}

The invalidation can happen directly in the write flow or through an event handler triggered after the data changes.

invalidateByCurrency can use an index that associates each currency with the cached reports that depend on it.

The next request will miss the cache, generate the report again, and store the updated result. A TTL can still be used to remove results that are no longer requested, but it is a secondary mechanism rather than the main invalidation strategy.

When it fits

Distributed memoization is a good fit when:

The operation is deterministic.
The same inputs appear frequently.
Results are relatively small.
The operation or its dependencies have a meaningful cost.

Possible use cases include pricing calculations, reports, data transformations, external API calls, machine-learning inference, and business rules engine evaluations.

I would not add this to a cheap operation or one where inputs rarely repeat. In those cases, the result store becomes another dependency without avoiding enough work to justify it. The pattern becomes useful when the hit rate is high enough for a lookup to regularly replace an entire chain of computation and network calls.