Designing Type-Safe APIs

So much of programming is about using the code of other people.

When we start a new project “from scratch”, we often end up weaving together frameworks, libraries, and tools built by hundreds and hundreds of people from all over the globe.

In a way, our ability to build successful projects depends on whether their code can be combined in new and interesting ways! API design is therefore an incredibly central problem.

The API, or Application Programming Interface, refers to how you interact with some piece of code — whether it's an HTTP endpoint, an object with properties and methods, or just a simple function.

So what makes for a great TypeScript API?

If you got to this chapter, chances are you're thinking that it comes down to one thing — writing good types ✨

That makes a lot of sense, types are the language of API design in TypeScript! The more precise the type, the more potential runtime errors can be caught ahead of time, so it seems evident that precise types improve the developer experience.

But from time to time, hovering over a seemingly harmless red squiggle forces us to reconsider this position... 🔎

😵

I bet you've experienced similar errors in your TypeScript journey. This one comes from @tanstack/react-table, a very popular React library for building complex tables. What went wrong here?

I can tell one thing: library authors do not intend to make you read giant walls of text that make you feel miserable. They only want to prevent you from shooting yourself in the foot by misusing their code. Yet, like everything in programming (in life?? 😵‍💫), it seems like precise types come with tradeoffs.

The truth is that there is more to API design than just type safety. Developers using our code will spend a significant portion of their time debugging and reading the type errors we throw at them. The good news is that TypeScript gives us a lot of ways to control this crucial aspect of the developer experience!

In this chapter, we will put ourselves in the shoes of an open-source developer. We are about to build a library together and focus on how we can guide our users to success through great error messages and helpful auto-complete suggestions!

The principles we are going to follow are simple:

1. If it type-checks, it should work.
2. Error messages should be short and easy to understand.
3. Auto-complete suggestions should nudge users toward working code.

Along the way, I'll share all the undocumented techniques I've collected over the years from the best open-source libraries out there to make TypeScript APIs truly delightful.

Let's get to it!

A tricky problem

We are building TrickTok 🛹 — a social network to share skateboarding trick videos! Of course, we chose TypeScript as our backend language. The product is simple: you can look at trick videos in a feed, open the details view, like them, and post comments.