Schema types a how to use it

[pepa-linha]

Hi, I am dealing with the question of how to correctly use the types returned by the API.

If I call the API, the result is returned typed, that's actually cool.

But, I need to put the returned data somewhere and I don't know how to simply get the type there. For example, a component that has props of a certain type (same as the data returned from the API).

There is an example on the website

type MyType = components["schemas"]["MyType"];

This is of course possible, so I should for example

type MyType = components["schemas"]["MyType"];
type ComponentProps = {
     data: MyType
}

But I wouldn't want to write such a notation manually, because I have hundreds of such types in the current API.

Is there any way to write it better or... maybe just a TypeScript question, can't it be written so that I just type MyApi. and get help for all types?

---

Maybe my question is related to this PR:
#1414

Thanks

[drwpow]

I wouldn't want to write such a notation manually, because I have hundreds of such types in the current API.

Is there any way to write it better[?]

This is a great question! Backing up a bit, the expectation of this library is to help you consume types from your API. So by its nature, it will be most-heavily used while sending/receiving data from an external source. That’s why openapi-fetch was created—to reduce boilerplate code while fetching to/from your API (and was designed in such a way that it can be wrapped by many libraries, such as React Query).

Beyond this, the assumption is that your core business logic is structured in a way that makes the most sense to the application. Having an API dictate the props passed to your component is a slight anti-pattern as a general rule, because an external API can’t take responsibility for how your internal biz logic should/shouldn’t work. So as a general rule, redeclaring your types manually is probably a good idea, because then, say, you could release a V2 of your API, or even pull the data from other sources, and then it’s not permanently attached to one single API’s historical data structures.

But maybe there are shared types that make sense to export, e.g. your API has a components["schemas"]["User"] type that gets passed around everywhere. Having a src/types/user.d.ts type may help:

import { components } from './my-schema';

export type User = components["schemas"]["User"];

Then, externally, referring to type User is opaque and could refer to something from the original API, or it could not. It could be swapped out at any point in that file, or extended with additional properties, without affecting either the API or the consumer application.

So to condense that down into loose recommendations:

• Write your app types the way you need first. Structure them according to core models (e.g. src/type/user.d.ts). If those happen to coincidentally match your API schema, great—save some typing by referring to the generated types. But in most cases they won’t match 1:1, so managing the types manually your application depends on will be the least work longterm.
• Use utilities for fetching/sending data. openapi-fetch is the recommendation, but use what makes the most sense for you
• Use inference where possible. From your example, maybe use ComponentProps["data"] more often than MyType. Chances are in most places in your app, you’re more concerned with the type of a prop you’re using and not the original API data (as that may get split up/rearranged as it’s passed through different components).
• Use the original API syntax. There’s a short section in the docs called “embrace snake_case.” In short, if you have a user_id field you get from the API, and you need pass user_id back in some request bodies, don’t bother renaming it to userId just to match JS style. That’s unnecessary work, harder to type correctly, and can introduce bugs.
  • Going futher, develop your own styleguide for naming. user_id is clear it is “owned” by the API; userId suggests, instead, that it is a property of the app. Only convert names when you are delegating responsibility to the app (and if you are, then the original generated types don’t matter because it’s no longer directly connected to the API anymore)
  • Likewise, just use components["schemas"]["my_type"] rather than MyType when you are explicitly referring to types from the API. The former will never break, and is explicit where its source is. The latter alias should only exist when you want them to diverge over time (first point).

---

This just explains some of the philosophy/reasoning with this library. The initial example is contrived and just shows people how it works from a TypeScript perspective, but don’t take that as advice. Follow your gut—if something feels like too much work, it probably is! 🙂