Solving the internal / external API riddle

Tom MacWright

on

Mar 27, 2025

I’ve been thinking about that APIs and applications question again for Val Town. We’re trying to resolve two priorities: rapidly developing features, and providing an API for our users. As it turns out, some of our tools are well-suited for rapid development, and others shine when creating externally-consumable REST APIs, but we haven’t found a way to do both yet.

For application development, we want to move as fast as possible. A lot of pull requests include both a feature in our Remix-based frontend and some backend functionality, either in Remix loaders, a tRPC route, or, less often, a new route in the Fastify server that powers our public API.

Specifically, the workflow of using tRPC and Remix is pretty spectacular: their homepage example tells most of the story. You write a method on the backend and the frontend tRPC client is immediately able to call it with the correct TypeScript types for both inputs & outputs. It all works without code generation, and minimal boilerplate. The developer experience is extraordinary.

On the other hand, we’re also trying to give our users the ability to build on the Val Town platform in all kinds of new ways. When we introduce something like Projects, we want users to be able to programmatically create projects and files within them. Our SDK should let them do that on day one. But right now, it doesn’t: we built the application interface for projects using tRPC and Remix, and then implemented the same with Fastify so that we have an OpenAPI spec that includes it, and then we can generate our SDK with that OpenAPI spec.

Could we both iterate quickly on the application layer and provide a lot of functionality programmatically to users? Possibly! But there are a lot of dragons here.

Remix loaders are definitely not a public API. Since the introduction of Single Fetch, loaders don’t even output JSON, but they use turbo-stream. Remix loaders definitely aren’t the REST model.tRPC is probably a bad way to implement OpenAPI. tRPC does technically kinda support OpenAPI via trpc-to-openapi, but the first-party support is archived and the fork doesn’t have much uptake, so this is really a fringe ability that I wouldn’t count on. We’ve experimented with allowing people to make programmatic requests against our tRPC routes, but this always ended up in disappointment. The actual requests and formats that tRPC uses for communication are an implementation detail. tRPC is not a REST provider.Building Fastify routes and generating SDKs for every feature, before we can even start on frontend development would introduce a tremendous amount of friction into our development process and create a waterflow between API design and frontend implementation. Imagine having to write a REST API method, merge and deploy it, generate a new SDK and release it as an NPM module, just to install that new SDK version into the application and start building a frontend feature.The OpenAPI specification does not support Server-Sent Events. Thankfully, Stainless, which helps us produce our SDKs, has its own support, but it’s disappointing that such a central specification for designing APIs won’t actually be able to describe our current API surface in full.Batching is good and we’ll lose it. tRPC supports batching requests, and Remix’s Single Fetch batches requests for nested loaders. This is a real benefit for frontend applications like Val Town: we tend to make a lot of HTTP requests, and request overhead is a real problem. Generic request batching is not something you can do with OpenAPI or any of these generated clients.

Here’s a quick table survey of the solution space that I’m aware of:

As you can see, there are a few systems that try to provide first-class support for both REST-based APIs that we can generate an SDK around, and RPC-like clients with which we can iterate quickly. Unfortunately, Hono, the most established option and one I’m pretty optimistic about - which supports both OpenAPI and RPC - has a fairly severe bug for using the two together. oRPC is extremely promising, but a new and fairly single-handed effort. stl-api is interesting, but in an alpha stage of development with no releases yet and very little development happening.

We’re going to experiment with a strategy to build our SDKs quickly and locally so that we can develop frontend features against the Fastify server. In parallel, I’ll probably kick the tires on oRPC and Hono as alternative approaches to this problem.

Decisions like this can cause a lot of churn, which hurts development momentum and makes it harder for everyone to understand the codebase, so it’s a decision we’re making pretty methodically and incrementally.

Have you seen good solutions to this problem? Let us know!