Technical Articles

Blog


# TL;DR

_This is not a library or framework. It is rather a simple solution to implement fullstack typesafe APIs without external dependencies._

You can have the cake and eat it too.

End-to-end type-safe APIs without dependencies or ecosystem buy-in. Just your REST APIs, some TypeScript, and a happy developer.

We only want effortless, type-safe APIs all the way down the stack. This is how it should work:

<div class="video-container">
  <video width="320" height="240" autoplay muted loop>
    <source src="/images/blog/typesafe_apis_video.mp4" type="video/mp4">
    Your browser does not support the video tag.
  </video>
</div>

And that indeed is how it works!

The concept is very simple: TypeScript API controllers that expose all needed typing information and runtime type safety thanks to standard JSON Schemas.

Links to the repo and CodeSandbox are at the end of the article.

# The Background

With every year that passes in our exciting little bubble of web development, it seems to me that we come closer and closer to the final end goal: The coupling of stellar developer experience, stability, speed of development, and the effortless expression of business needs using code and infrastructure.

This might also just be the natural path every software engineer wanders throughout their career. Or a mixture of both in a subculture like ours where we reinvent the same things over and over again, for good (reinventions bring the potential for radical innovation).

I remember well that beginner-dev me, when building fullstack apps for the first time, using good ol' Express, wanted to find a way to unify type information (from database schemas down to the frontend), so that repeating that information in every part of the stack could be avoided. I was playing around with every tool I could find and also committed a few crimes along the way. But I guess the only developer out there who isn't, is the one who never coded.

Then GraphQL came. And I still remain convinced that this is one of the most misused technologies in recent years, but it has shifted the whole community in the right direction. In my opinion, the great hype and adoption of GraphQL came to be because it provides a type system for APIs. I know that that's just one of the features of GraphQL and definitely not the reason it was invented, but it was the reason why it became so popular. Generating TypeScript types or SDKs for every programming language - a game changer. Sprinkling a few million bucks of marketing on it, calling your company like the moon landing, and dang 💥 - people realize that having typed API clients is a good thing, and so everyone switches their APIs to GraphQL.

Don't get me wrong - GraphQL is amazing and has its valid use cases, but for most APIs, a well-documented REST API is probably the better choice.

Providing fully typed-out APIs isn't something GraphQL invented - in fact, we had that already decades before - SOAP & WSDL, Swagger, and OpenAPI later.

With TypeScript surging in popularity, for good reason, this aspect became more and more important. Knowing the exact request and response types of the APIs you are calling without having to maintain them yourself is a huge productivity boost.

Then tRPC was born. The logical successor of SOAP, OpenAPI, and GraphQL.

tRPC is the synthesis of the learnings of the past - and applies all the good we gained from the predecessors, while weeding out the dark sides (code generation, outdated dependencies, vendor lock-in). It's the next logical step for fullstack TypeScript development. Why would you want to generate types for an API which already has all the types defined, in the same programming language, heck, most of the times even in the same repo?

So when I first saw tRPC, I was like:

> This is it. This is what I was waiting for. This is what beginner-dev me was actually dreaming of.

I played around with tRPC and deployed a few APIs with it. I liked it. But some things still bugged me.

You still have to re-declare your schema using Zod, for example. In addition to that, similar as with GraphQL, you have to buy into a whole new ecosystem again. Can't we just stick with our proven REST APIs, and type them out?

**So I came up with a new approach, an approach that actually doesn't require any external libraries but still gives you end-to-end type-safe APIs.**

And don't get me wrong, tRPC is amazing, but this is just a different and less opinionated way of reaching the holy grail of e2e type-safe APIs.

# The Idea

The core idea is the following: Instead of re-declaring the schema, JSON schemas are auto-generated (and it's not even needed to do that during development, so not a blocker or slow-down factor) based on the response and request types of the API controllers.

What I really love about this approach is that it has 0 dependencies, is very transparent, while offering all the upsides the evolution of tooling over the past years gave us.

It essentially consists of 3 parts:

- A TypeScript API Controller that exposes input and output types.
- Two utility types to extract types on the client side.
- A TypeScript to JSON Schema Generator for type-safe runtime APIs.

And that's it. Here's a simple example, step-by-step:

## Step 1: Declare your controller

```typescript
import { Infrastructure } from "@local/api-utils";
import reqJsonSchema from "./GetCharacter.request.schema.json";

export type GreetingQueryParameters = {
  // Use JSDoc to enforce additional input data validation rules
  /**
   * @minLength 3
   * @maxLength 100
   * @description the full name of the user
   */
  fullName: string;
};

export type GreetingResponse = {
  greeting: string;
} & Infrastructure.BaseControllerResponse;

export class GreetingController
  extends Infrastructure.ControllerWithQueryParametersValidator<GreetingQueryParameters>
  implements
    Infrastructure.IController<
      GreetingQueryParameters,
      unknown,
      GreetingResponse
    >
{
  constructor() {
    super({
      inputSchema: reqJsonSchema as unknown as Infrastructure.TJsonSchema,
    });
  }

  public async execute({
    queryParameters,
  }: Infrastructure.ControllerExecutionParameters): Promise<
    Infrastructure.ControllerResponse<GreetingResponse>
  > {
    this.validateQueryParameters(queryParameters);

    const { fullName } = queryParameters;

    return {
      statusCode: 200,
      body: {
        greeting: `Welcome, ${fullName}`,
        type: "success",
      },
    };
  }
}
```

## Step 2: Implement the client query

```typescript
// Get your controller type
import type { GreetingController } from "../../backend-api";
import {
  ControllerExecutionSuccessResult,
  ControllerQueryParameters,
} from "@local/api-utils";

export async function greetingQuery(
  // Fully typed input parameters, derived from the controller
  params: ControllerQueryParameters<GreetingController>
) {
  const urlParams = new URLSearchParams(params).toString();
  const fetchResult = (await fetch(
    `http://localhost:3333/greet?${urlParams}`
  ).then((res) =>
    res.json()
  )) as ControllerExecutionSuccessResult<GreetingController>;
}
```

## Step 3 (optional): Generate the JSON schema for runtime type safety

```bash
npm run generate-json-schemas
```

# Thanks for reading!

I've used this approach at my startup for nearly 1.5 years now, and we are super happy with it.
Let me know what you think about it.

With the rise of AI-assisted coding, approaches like these will become more and more relevant. If your AI assistant always has all the type information at their disposal, generating clean, functioning, and nice code will be a breeze. Set yourself up for success in this new phase of turbocharged application development.

You can find the GitHub repo and a link to codesandbox, where you can try it out yourself, here:

- [Link to GitHub repository](https://github.com/scriptify/vanilla-typesafe-apis)
- [Link to Codesandbox](https://codesandbox.io/p/github/scriptify/vanilla-typesafe-apis/main)

**But of course, having type-safe APIs is just half the battle.**

Structuring your API code in a scalable way is the other side of the coin.

_The example repo contains an API and a React app, co-existing in an NX monorepository, but the concept itself is compatible with right about any backend/frontend framework/library and even JS runtime._

I will eventually create an article series about pragmatic Domain-Driven Design in TypeScript using Vertical Slice Architecture. The series will be called

> You might not need a Node.js Framework (...and neither an ORM)


A pragmatic approach for typesafe APIs using nothing but vanilla TypeScript

You don't need GraphQL or tRPC


> This article is continously updated

## Abstraction

Do not create high levels of abstractions early on, the same way you don't build the full product with all features for your startup, but go with an MVP. You don't know what needs the future, and here we are talking about hours not years, will bring. Stay low level until you see patterns emerging. If an abstraction will save you time, implement it. And this has nothing to with a clean code architecture.

## Interface and boundaries

Everything is an interface. Interfaces and clearly defined boundaries are the secret sauce to a scalable software architecture your future self will enjoy working in.

"Write modular code and monolith vs. microservice architecture becomes an implementation detail"

## TDD

First you deny it, then you fear, then you try it, then you can't live without it. But it doesn't make sense to apply it before you don't understand software architecture well.

## DDD

same here

- Most chaotic codebases get born because files get created in random locations, without any structure. In addition, those files contain functions that serve multiple purposes and handle data of various formats - no knowing which layer the actually belong to. Humans need structure, patterns - in order to be able to think and make sense of something. The larger and more interdependent a system gets, the more important that clear structure becomes. The lack of good architecture won't be noticable during the first days, weeks, sometimes even months. But then it bites. And uh, do those bites hurt. They hunt you at night, make you sleepless, force you to deepen your coffee addiction. It's rarely "just a simple project", an "MVP", a "PoC". Build solid, build for the future, save tears (there sure are moments where those are needed, and coding shouldn't be one of them).

## Vertical sliced vs. horizontal architecture

## Feature flags

- Feature branching etc
- Only makes sense with a good testing strategy and software architecture

## Architecture > Technology Choices

Doesn't matter if you use GraphQL or Rest, when the underlying API is a mess. The other way around though, adding GraphQL to a well architected API, or switching from Node to Deno, is straightforward, because a good architecture is resilient to change in infrastructure.

## Do not name Experiments "Test[...]"

Small thing I noticed even doing myself sometimes. Calling an experimental code (e.g. a React component) "TestXYZ", e.g. `TestComponent`. It should rather be called `ExperimentalComponent`

## Everything is an API ... or why you need incremental testing

...and you always develop an SDK for your future self or your team.
Just the way of calling that API/SDK might differentiate: A normal function you import, a React Component, a REST or GraphQL API. They belong to different layers for sure, but might be re-used in all different places. So make sure to make them testable and mockable right from the start.
-> Incremental Testing

## Well-architectured monorepos

Monorepositories without layered architecture and a good testing strategy will turn into an uncontrollable spaghetti mess, which will feel like you just dumped your whole code into one giant file.

## Some concepts to write about

- No library typesafe State Management for React
-

## AI Project Ideas

Store and analyze code base abstractions - to develop new features; with enough abstractions the LLM can lookup (e.g. from a Vectore Database) everything relevant and develop whole features.
We just need a documentation of all internal APIs and our design system, so the AI could potentially just write features on it's own.


Some insights I gathered over the years while developing software

Idea dump - Things I learned (the hard way)


Remember: _This is opinion_ - there are no silver bullets, and all models are wrong, some are useful.

"Microservices" is actually a DevOps term - it is _how_ you deploy the different modules of your app. But actually, the logical boundaries of your app shouldn't be the same as the physical ones. In fact, in a clean architecture, it shouldn't matter _how_ you deploy your modules: As a modular monolith or several microservices. Other factors should decide that. Today, I'll guide you through an example on what that could mean in practice, using an NX based monorepo, TypeScript, Node.js and Serverless.

> Talk about the end of zero interest rates


Moduliths in a Monorepo

CTO & Founder at Carlito. Web & TypeScript Expert. Web Audio Enthusiast.


Find me on

In this phase we will define how your organization wishes to be perceived by consumers. What do you want people to think about your product or service?


Strategy

Based on the research, strategic designs solutions will be explored. Multiple route will be presented and the selected will be further developed.


Execution

This is the phase were the launch communication plan will be developed. The key messages will be defined and tailored to the audience of the brand intact.


Launch

The approach

Process Delivers Value

2014 — Present

Projects

Role

website

Tech

Carlito


I was the first engineer on the team and developed the first fully functioning web application which was already used by major clients of the public sector. We then scaled to a team of 8 engineers in the course of two years. Most of the APIs and frontend apps I developed there are still in use daily and serve a huge customer base.


Cloud-based photogrametry platform for the construction industry

Founded

Photogram


I've developed this tool prior to the existence of monorepo tools like NX. It is essentially opinionated tool to develop React and Node.js applications within a monorepository, using TypeScript.

It was used by all my startups and some agencies. As soon as NX become more stable, we switched from Cantara to NX, but it served us well for many years.


TypeScript, Node.js & React Monorepo Devtools

GitHub

Cantara

3-dimensional, generative soundscapes platform and editor for better focus and sleep

Soundescape.io


A Visual Gatsby.js Jamstack Website Builder with a ZIP export functionality.

<div class="video-container">
  <iframe width="560" height="315" src="https://www.youtube.com/embed/QbT6fpgY210?si=dU0sD4vvRwZsFsNx?controls=0&mute=1&autoplay=1" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div>


Maximilian Torggler