Have you ever needed to synchronize types in your frontend app with the backend API?
If you ever had an API action defined like that in your controller:
and fetched this data using TypeScript in the following way:
at some point, you probably also experienced the desynchronization of backend (C#, in our example) and frontend (TypeScript) types definitions. What if someone has changed the C# version of
UserViewModel, but no one corrected its TypeScript’s equivalent?
Your TypeScript fetching code will tell nothing about that. There will be no error, even though the fetched data doesn’t match the expected
I’ll try to address this issue in this article 🙂 Let’s see how typing API responses with
zod can help us here.
First, why would we want to keep the backend and frontend models in sync?
For me, that’s the purpose of using TypeScript. We want our code to be as well-typed as possible.
For instance, we normally want the data displayed to the user to be fully typed. TypeScript enhances our programming experience by providing us with typing information. Thanks to that, we know what is what and what contains what. We also express what types of data we expect in particular cases.
The APIs mostly return JSON data, which can be anything. Because of that, it is much easier to have the data returned from the API fully typed in TypeScript. Thanks to that, we know what properties are available on the data models received from the API and whether we can use and display them to the users.
The sample code used within this article is available on GitHub. We will use ASP.NET Core (C#) and React (TypeScript) apps as examples.
As we saw in the beginning, a classic example is an API controller that returns a strongly-typed data:
The returned data type is a collection of
UserViewModel objects. Here’s the C# definition of this type:
Its equivalent is also defined on TypeScript side:
Cool. With this simple code, we can create a
usersService.ts file and fetch our users’ data from the API. Notice how we make this call strongly typed:
Everything looks legit. We can use the data retrieved from the API in
UsersList component and everything is nicely typed:
The data is even perfectly displayed:
So, what can go wrong here? 🤔
Let’s say that a backend developer implements a requirement to rename “loyalty points” into “fidelity points”. Easy. (S)he renames
LoyaltyPoints property in the C#’s
The new C# model looks as follows:
Nice! The backend dev is a very good programmer, so (s)he even launches the React web application to make sure that everything still works correctly and there are no errors in the dev console:
After a quick look, everything looks awesome. The users list is displayed, there are no errors in the console. Apparently, these test users don’t have any loyalty points assigned – that’s why the empty values in “Loyalty points” column. What’s more, translators will update the column’s translation later. We are good! Let’s go on prod! 😎
I guess you already know what went wrong here. API definition changed, but TypeScript didn’t inform us about that 😔 Our
UserViewModel still uses the old property name:
However, it still works. When rendering the
UsersList, we simply get
undefined in place of
fidelityPoints property is already there at runtime:
With the current solution, we will never be informed soon enough about API models changes in our React application. In the best case, we’ll get an
null error when clicking through the app. However, it’s usually an end user who finds such problems on production. This is definitely not what we want 😶
We can solve this problem by typing API responses with zod. Let’s now see how to do that.
Our remedy –
zod – is quite a decent npm package with ~600k weekly downloads. Its GitHub page advertises the library as TypeScript-first schema validation with static type inference.
You can definitely do many things with zod. It can be used together with libraries like react-hook-form to perform complex forms validation. However, in our case, we’ll treat
zod as a solution for better typings in TypeScript.
First, let’s install
zod into our React application:
npm i zod
zod, we define our types in a slightly different way. Instead of creating a
interface directly, we first create a schema. In our case, we can define a
z.object creator function:
Few interesting parts here:
Line 2: notice how
zodhelps us to define types like
Guidwith built-in schemas like
Line 8: first, I used
AddressViewModelSchemahere. This is a custom schema of an
AddressViewModelobject, which is another type used internally in
UserViewModel. You can use such custom schemas in other schemas. Also notice the
nullable()call here, which makes the address property nullable
First step done – we have our
UserViewModelSchema. But can we use it instead of
UserViewModel type? Not really. Schema is used for validation purposes only. We still need the
UserViewModel TypeScript’s type.
zod comes with a handy
z.infer function that allows us to infer the type from the schema.
userViewModel.ts file looks as follows:
We can use the exported
UserViewModel type as previously used type. It’s an equivalent to the previous, "classic" type we had defined, but this time inferred from
One last step is to make use of
UserViewModelSchema. Let’s modify the
getAllUsers function from
usersService to validate the data received from the API against our schema:
Notice the usage of
z.array. This function call tells
zod to validate an array of objects meeting the rules defined by
UserViewModelSchema, not a single object.
Now, let’s run our React app and see what happens when we click the “Fetch users” button:
This is awesome! Exactly what we wanted – a schema validation error for API response. Notice how the error message precisely points to the missing (or wrong, in other cases) property. It tells us we expected a
loyaltyPoints, but instead we received
undefined. The reason for this error message is that the
loyaltyPoints field is
Required in our schema.
UserViewModelSchema and updating the
UsersList component accordingly, everything works fine again.
We are now fully typed and prepared for the future, in case an issue with desynchronization of frontend and backend typings happens again 🚀
Today, we’ve seen how typing API responses with
zod can help us detect frontend and backend models desynchronization. Schema validation throws errors when the data doesn’t match its expected shape.
zod is an extended library with many options. I recommend exploring them on your own. An interesting feature we didn’t cover in this article is strict mode, which doesn’t allow additional fields not present in the schema definition when validating the data object.
You can explore the complete code presented in this article here.