V16: Updates openapi-ts client and deprecates tryExecuteAndNotify

[iOvergaard]

Description

This pull request includes several changes to improve the codebase, update dependencies, and enhance error handling. The most important changes include dependency upgrades and modifications to error handling and server connection logic.

Breaking changes

• The function tryExecuteAndNotify has been deprecated, and developers should instead use tryExecute, which now covers the same functionality
• The function tryExecute now has a required host parameter, and developers can mostly convert directly by referencing this:

// Before
await tryExecute( ApiService.getSomeThings() );

// After
await tryExecute( this, ApiService.getSomeThings() );

You can optionally suppress notifications by adding an options object:

await tryExecute (this, ApiService.getSomeThings(), { disableNotifications: true } );

Other changes

New features

• All errors returned from tryExecute will be of an UmbError instance such as UmbApiError, which has a required problem details object among other things
• Developers working with custom API clients can now bind Umbraco's interceptors to get auth and error handling more easily:

import { UmbApiInterceptorController } from '@umbraco-cms/backoffice/resources';
import { client } from '../generated/client.gen.js';

const interceptorController = new UmbApiInterceptorController(this);
interceptorController.bindDefaultInterceptors(client as any);

Dependency Upgrades:

• Upgraded @hey-api/openapi-ts from version 0.61.3 to 0.66.1 in package-lock.json and package.json. [1] [2]

Error Handling Improvements:

• Replaced ProblemDetails with UmbProblemDetails for better error handling and consistency across various files (app-error.element.ts, installer-database.element.ts, installer-error.element.ts). [1] [2] [3] [4]

Server Connection Enhancements:

• Modified UmbServerConnection to extend UmbControllerBase and use tryExecute with the host parameter for improved server interaction and error handling. [1] [2] [3] [4]

[github-actions]

Azure Static Web Apps: Your stage site is ready! Visit it here: https://victorious-ground-017b08103-18939.westeurope.6.azurestaticapps.net

[Copilot]

Copilot reviewed 174 out of 176 changed files in this pull request and generated no comments.

Files not reviewed (2)

• src/Umbraco.Web.UI.Client/package-lock.json: Language not supported
• src/Umbraco.Web.UI.Client/package.json: Language not supported

Comments suppressed due to low confidence (3)

src/Umbraco.Web.UI.Client/src/packages/core/object-type/object-type.repository.ts:17

• Ensure the updated tryExecute call still handles error notification or propagation appropriately, as the behavior may differ from tryExecuteAndNotify.

return tryExecute(this.#host, ObjectTypesService.getObjectTypes({}));

src/Umbraco.Web.UI.Client/devops/openapi-ts/openapi-ts.config.js:4

• Review the removal of the 'client' property in favor of adding the 'legacy/fetch' plugin to ensure that legacy fetch functionality is preserved.

export default defineConfig({

src/Umbraco.Web.UI.Client/src/apps/app/app.element.ts:149

• Verify that the new instance-based initialization of the API interceptor does not impact the expected binding of interceptors, ensuring consistent API error handling.

this.#apiInterceptorController.bindDefaultInterceptors(OpenAPI);

[github-actions]

Azure Static Web Apps: Your stage site is ready! Visit it here: https://victorious-ground-017b08103-18939.westeurope.6.azurestaticapps.net

[github-actions]

Azure Static Web Apps: Your stage site is ready! Visit it here: https://victorious-ground-017b08103-18939.westeurope.6.azurestaticapps.net

[github-actions]

Azure Static Web Apps: Your stage site is ready! Visit it here: https://victorious-ground-017b08103-18939.westeurope.6.azurestaticapps.net

[github-actions]

Azure Static Web Apps: Your stage site is ready! Visit it here: https://victorious-ground-017b08103-18939.westeurope.6.azurestaticapps.net

[github-actions]

Azure Static Web Apps: Your stage site is ready! Visit it here: https://victorious-ground-017b08103-18939.westeurope.6.azurestaticapps.net

[leekelleher]

I've tested this out around the backoffice, all areas are working as expected.
I also tried adding custom notifications (via INotificationHandler<T>) and they still work nicely too! 🚀

I'm happy with the initial review of the code changes. I'm sure there will be refinements in the next PRs. 😎

[arknu]

@iOvergaard Maybe you should add some documentation on how actually to call/implement custom backoffice APIs for the new backoffice. Because I had to guess and look at source code to work out how to at least get something that worked. There is some documentation on the server-side, but absolutely nothing on the client-side.

The most annoying thing about the new backoffice is the complete lack of documentation for even the most basic of tasks.

[iOvergaard]

@arknu That is an interesting topic to document; There is nothing here specific to Umbraco apart from how to borrow/hook onto the access token from Umbraco for your API calls-- and that, I agree, is not documented very well.

Hint: Try to run the command dotnet new umbraco-extension --include-example in an Umbraco solution to see how a custom API could be implemented.