Migration path for after name is deprecated

[paambaati]

See #606 (comment) for a related issue.

The issue
name in configuration is deprecated, and will eventually be removed. Without that configuration, the default class won't be created.

Consider this example –

const client = new MyClient({
    TOKEN: '<INSERT API KEY HERE>',
});

const things = await client.test.getThings();
console.log(things);

In this example, MyClient is the default client that is created only when name is specified, and it offer a nice wrapper for the base request configuration – this lets us set up the token. test is a service, and getThings is an API endpoint.

Without MyClient generated, there is no straightforward way to configure the token for all requests.

@mrlubos and the rest of the hey-api team – can you folks please add more information about a) why this is being deprecated and b) what the client configuration API will look like once name option is gone?

[mrlubos]

Thanks, let's start here!

Without MyClient generated, there is no straightforward way to configure the token for all requests.

You can absolutely configure token for all requests without MyClient. You can modify the OpenAPI object today, or use createClient() in the new Fetch API client. You could even use interceptors to alter each request before being sent.

what the client configuration API will look like once name option is gone?

The current answer is the new Fetch API client – make sure to view the demo too. A similar solution will be offered for other clients.

why this is being deprecated

There are a few reasons. name will create a different client instance every time it's run. To create two instances, you'd have to run it twice, and you'll end up with two different files encapsulating the same API. With clients, you generate everything only once, and then use createClient() to create as many encapsulations as you want. In fact, you're never even generating the client yourself anymore, it's a standardised 3rd party package @hey-api/client-fetch.

name is not the default solution and it's not clear why. It's mentioned its purpose is to support multiple backend services. You can easily achieve that with the new clients as described above. Even if that was a legitimate feature, it's not clear why every client doesn't follow the same API. Why isn't there a default new Client() for those who have only one backend service? This leads to some people using a completely different set of APIs than others – appClient.organizations.createOrganization() vs OrganizationsService.createOrganization().

As a result, custom instances suffer from unique bugs that aren't present in the default approach, see #517. It's harder to prioritise such issues without knowing how many people use each approach. And even then, it's not reasonable to offer multiple API surfaces like that. If you're a new person using this package and follow the guide, as soon as you want to add another backend service, you have to rewrite all your code because the original approach didn't encapsulate everything in a client instance.

Finally, the new APIs are superior. Whether it's offering tree-shaking, customisable client instances per request, access to headers and raw request/response, or deduplicated parameter definitions. The only thing client instances got going for them is an SDK-like API encapsulation of all endpoints. That's a valid feature, but would be better addressed by generating a proper SDK, or perhaps offering a different signature to default clients.

Tl;dr standalone clients are easier to maintain, offer more features, and result in a faster and consistent generated code.

[paambaati]

You can modify the OpenAPI object today, or use createClient() in the new Fetch API client.

As a library author who cares about bundle sizes a lot, I'd prefer a native solution always, so I'm going to be defaulting tofetch for as long as I can.

Would it be possible to come up with a wrapper for the OpenAPI config so that I can configure the client in one shot? I absolutely love the simplicity of initializing the client with the token in one simple options bag and then have that used for all operations.

[mrlubos]

Sounds like the new Fetch API client with default config is your answer to both

[paambaati]

Does the new Fetch API client have to be bundled as a dependency for my downstream consumer if I'm a library author? Or does it transpile down to native fetch?

[mrlubos]

It's a dependency. It never transpiled down to native however, it generates a whole core folder. Now you have that folder (its equivalent) as a dependency

[benjamin-tessem]

@mrlubos Thank you for taking the time to explain the rationale behind the upcoming changes. I appreciate the efforts to make the package more flexible and feature-rich. However, as a library author who prioritizes stability and ease of use, I have some concerns with the current direction.

My primary concern is the frequency of breaking changes, which has been causing significant disruption to our development workflow. Every week, we find ourselves having to refactor large portions of our codebase to accommodate the latest changes, which is not sustainable in the long run.

While I understand the appeal of the new Fetch API client and the improved flexibility it offers, our use case revolves around a relatively straightforward setup where we need to dynamically make calls to different services within the API client. The current implementation, with the default class, suits our needs perfectly, and we would prefer not to have to reconfigure everything every time there is a release.

One potential solution that could address both our concerns and your goals would be to maintain the existing default class implementation alongside the new Fetch API client. This way, teams like ours who prioritize stability and simplicity can continue using the familiar interface, while those who desire more flexibility can opt for the new client.

Ultimately, our goal is to have a reliable and easy-to-use API client that doesn't require constant refactoring. We would greatly appreciate it if you could consider maintaining the existing default class implementation, at least for the time being, to alleviate the burden of frequent breaking changes on downstream consumers.

Thank you for your understanding and for the incredible work you've done on this package. We look forward to a productive discussion and a solution that works for everyone.

[mrlubos]

Started an issue around full SDKs, let's move the conversation there #926