Provide support for API versioning

[marcushellberg]

Is your feature request related to a problem? Please describe. Updating endpoints of an existing application can lead to a situation where the backend API does not match the API expected by running applications. Especially when using stateless backends.

Describe the solution you'd like There should be a way to version APIs or otherwise ensure that upgrading the backend does not break apps for active users.

Describe alternatives you've considered

Additional context

[Legioth]

We should keep in mind that API versioning as a general concept is also used for cases with an API is exposed for use by 3rd party clients or native mobile applications where it might be months or even years before all clients are updated. While there might also be a need in Hilla applications, the time window is also significantly shorter.

I'm not sure there's much that the framework can do to help here since only the application developer can understand the semantics of any endpoint signature change. Some things we could still consider to help are:

• Make it possible for the client to opt in to get notified if the backend has changed so that it can show a prompt to the user to refresh. This will obviously not directly help the end user but it will at least help resolve cases where things are broken because the developer did a reckless change.
• Make it possible to run different versions of the endpoints on different URLs so that the old deployment can be kept around for a while after a new one is deployed.
• Support default values for endpoint parameters so that it's still valid for an old client to call a method that has been updated to take an additional parameter (at the end of the parameter list).
• Make it possible for application developers to notice in case they are doing incompatible API changes.

[platosha]

• Make it possible for application developers to notice in case they are doing incompatible API changes.

I hope TypeScript sufficiently covers this already. Feel free to suggest if there is anything to improve though.

[Legioth]

TypeScript doesn't help for the situation when the application is redeployed so that the server has a new version of the endpoints while the user still has an old version on the client open in a long-running browser tab.

[tarekoraby]

Could it help if Hilla has a mechanism for marking endpoints or methods therein as deprecated (similar to GraphQL's field deprection)?

[Legioth]

Deprecation is a development-time strategy whereas the main problem in our case is a mismatch between different parts of the application while it's running.

Deprecation helps the developer keep the old API around for enough time after they've deployed code that would no longer use that API. The developer still needs to manage the process of introducing a new non-deprecated API side-by-side and making a guess on when it's safe to deploy a version where the previously deprecated API is removed.

[jeacott1]

This is a huge red flag for me if there's no means to control this. usually I'd have 2 things going on.

1. I'd transmit a X-Client-Version header on every request.
2. I'd be marking model fields with @JsonIgnoreProperties(ignoreUnknown = true) and managing validation rules as appropriate. And adding/removing fields, altering structures as part of the usual multistep release process to accommodate backward compatibility over transitions.

Does hilla do anything itself with this annotation in particular? will the generated hilla typescript balk if it receives extra fields from the frontend its not expecting?

[Legioth]

What makes you need that level of control? I'm asking because we know we need to add something, but we haven't yet understood the requirements well enough to be certain on how to best balance between simplicity and flexibility.

Would you use Hilla also for other clients than a web client using the generated TypeScript? Do you have experiences of trouble caused by a web client becoming outdated because the user keeps their browser tab open for a long time without reloading?

[jeacott1]

@Legioth that's normal zero downtime deployment no? if we release 5 times a day, and have lots of people actively working on a site why would I expect them to stop their work, and reload their site just because we rolled out a new version of the backend? I expect to be able to reasonably manage compatibility to facilitate that. Not all updates involve dto model changes, but where the api changes it should be manageable. We of course have the option to pin a backend version to a frontend, but running multiple backend versions for any length of time is just a waste of $$$. Assuming we have multiple servers running for any given backend any rolling update is going to require multiple backend versions be present at once. I'd likely want to be rolling out front and backend independently and be in a position to revert either if there's a problem.

Would you use Hilla also for other clients than a web client using the generated TypeScript?

I'm not sure what you are getting at here, are you referring to potential typescript based services? - I'm personally not interested but I can certainly see the usecase. and again, I'd need to update these independently of the service they are talking with (or visa versa)

Do you have experiences of trouble caused by a web client becoming outdated because the user keeps their browser tab open for a long time without reloading?

Absolutely! at some point it becomes reasonable to force an update, but certainly not after a single version.