docs: adds an article on how to execute requests

this also merges part information found in other articles

Author: iOvergaard

16/umbraco-cms/SUMMARY.md

@@ -186,6 +186,7 @@
   * [Fetching Data](customizing/foundation/fetching-data/README.md)
     * [Fetch API](customizing/foundation/fetching-data/fetch-api.md)
     * [HTTP Client](customizing/foundation/fetching-data/http-client.md)
+    * [Executing Requests](customizing/foundation/fetching-data/try-execute.md)
   * [Working with Data](customizing/foundation/working-with-data/README.md)
     * [Repositories](customizing/foundation/working-with-data/repositories.md)
     * [Context API](customizing/foundation/working-with-data/context-api.md)

16/umbraco-cms/customizing/foundation/fetching-data/fetch-api.md

@@ -114,6 +114,8 @@ The above example serves to illustrate some of the process to make a request to
 
 Regardless of method, you can execute the fetch requests through Umbraco's [tryExecute](https://apidocs.umbraco.com/v16/ui-api/classes/packages_core_auth.UmbAuthContext.html#tryexecute) function. This function will handle any errors that occur during the request and will automatically refresh the token if it is expired. If the session is expired, the function will also make sure the user logs in again.
 
+**Example:**
+
 ```javascript
 import { tryExecute } from '@umbraco-cms/backoffice/resources';
 
@@ -127,12 +129,14 @@ if (response.error) {
 }
 ```
 
-{% hint style="info" %}
-The above example requires a host element illustrated by the use of `this`. This is typically a custom element that extends the `UmbLitElement` class.
-{% endhint %}
+You can read more about the `tryExecute` function in this article:
+
+{% content-ref url="../try-execute.md" %}
+[try-execute.md](../try-execute.md)
+{% endcontent-ref %}
 
 ## Conclusion
 
 The Fetch API is a powerful and flexible way to make network requests in JavaScript. It is available in all modern browsers and is the recommended way to make network requests in JavaScript. The Fetch API can be used in Umbraco to make network requests to the server. It can also be used to make requests to the Management API controllers. You can use the Fetch API to make requests to any endpoint in the Management API. You can also use it to handle responses in a variety of formats. This is especially useful, if you have but a few requests to make.
 
-However, if you have a lot of requests to make, you might want to consider an alternative approach. You could use a library like [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) to generate a TypeScript client. The library requires an OpenAPI definition and allows you to make requests to the Management API without having to manually write the requests yourself. The generated client will only need the token once. This can save you a lot of time and effort when working with the Management API. The Umbraco Backoffice itself is running with this library and even exports its internal HTTP client.
+However, if you have a lot of requests to make, you might want to consider an alternative approach. You could use a library like [@hey-api/openapi-ts](https://heyapi.dev/openapi-ts/get-started) to generate a TypeScript client. The library requires an OpenAPI definition and allows you to make requests to the Management API without having to manually write the requests yourself. The generated client will only need the token once. This can save you a lot of time and effort when working with the Management API. The Umbraco Backoffice itself is running with this library and even exports its internal HTTP client. You can read more about this in the [HTTP Client](http-client.md) article.

16/umbraco-cms/customizing/foundation/fetching-data/http-client.md

@@ -22,50 +22,19 @@ The above example shows how to use the HTTP client to make a GET request to the
 
 The HTTP client automatically handles authentication and error handling, so you don't have to worry about those details. It also provides a convenient way to parse the response data as JSON.
 
-## Executing the request
+## Using the HTTP Client
 
-The Backoffice also provides a `tryExecute` function that you can use to execute requests. This function will additionally wrap the request in a try/catch block and handle any errors that occur during the request. It will also show a notification if the request fails.
+The HTTP client is a wrapper around the Fetch API that provides a more convenient way to make network requests. It handles things like request and response parsing, error handling, and retries. The HTTP client is available through the `@umbraco-cms/backoffice/http-client` package, which is included in the Umbraco Backoffice. You can use it to make requests to any endpoint in the Management API or to any other API.
 
-```javascript
-import { umbHttpClient } from '@umbraco-cms/backoffice/http-client';
-import { tryExecute } from '@umbraco-cms/backoffice/resources';
-
-const { data, error } = await tryExecute(this, umbHttpClient.get({
-    url: '/umbraco/management/api/v1/server/status'
-}));
+The recommended approach to use the Umbraco HTTP Client is to use the `tryExecute` function. This function will handle any errors that occur during the request and will automatically refresh the token if it is expired. If the session is expired, the function will also make sure the user logs in again.
 
-if (error) {
-    console.error('There was a problem with the fetch operation:', error);
-} else {
-    console.log(data); // Do something with the data
-}
-```
-
-The `tryExecute` function takes the context of the current class or element as the first argument and the request as the second argument. Therefore, the above example can be used in any class or element that extends from either the [UmbController](https://apidocs.umbraco.com/v16/ui-api/interfaces/libs_controller-api.UmbController.html) or [UmbLitElement](https://apidocs.umbraco.com/v16/ui-api/classes/packages_core_lit-element.UmbLitElement.html) classes.
+You can read more about the `tryExecute` function in this article:
 
-It is recommended to use the `tryExecute` function instead of the raw HTTP client. It can also be configured not to show notifications, if you want to handle errors yourself:
-
-```javascript
-tryExecute(this, request, {
-    disableNotifications: true,
-});
-```
-
-### Cancelling requests
-
-The HTTP client also supports cancelling requests. This is useful if you want to cancel a request that is taking too long or if the user navigates away from the page. You can cancel a request by using the [AbortController API](https://developer.mozilla.org/en-US/docs/Web/API/AbortController). The `AbortController` API is a built-in API in modern browsers that allows you to cancel requests. You can use it directly with tryExecute:
+{% content-ref url="../try-execute.md" %}
+[try-execute.md](../try-execute.md)
+{% endcontent-ref %}
 
 ```javascript
-const abortController = new AbortController();
-
-// Cancel the request before starting it for illustration purposes
-abortController.abort();
-
-tryExecute(this, request, {
-    disableNotifications: true,
-    abortSignal: abortController.signal,
-});
-```
 
 ## Custom Generated Client
 

16/umbraco-cms/customizing/foundation/fetching-data/try-execute.md

@@ -0,0 +1,64 @@
+---
+description:: Learn how to execute requests in the Backoffice.
+---
+
+# Executing Requests
+
+When you make a request to the server, you need to execute it. This can be done using the Fetch API or the Umbraco HTTP client. The Backoffice also provides a `tryExecute` function that you can use to execute requests. This function will handle any errors that occur during the request and will automatically refresh the token if it is expired. If the session is expired, the function will also make sure the user logs in again.
+
+{% hint style="info" %}
+You can read the technical documentation for the `tryExecute` function in the [UI API Documentation](https://apidocs.umbraco.com/v16/ui-api/functions/packages_core_resources.tryExecute.html) class.
+{% endhint %}
+
+## Using the HTTP Client
+
+Here is an example of how to use the `tryExecute` function with the Umbraco HTTP client:
+
+```javascript
+import { tryExecute } from '@umbraco-cms/backoffice/resources';
+import { umbHttpClient } from '@umbraco-cms/backoffice/http-client';
+
+const { data, error } = await tryExecute(this, umbHttpClient.get({
+    url: '/umbraco/management/api/v1/server/status'
+}));
+
+if (error) {
+    console.error('There was a problem with the fetch operation:', error);
+} else {
+    console.log(data); // Do something with the data
+}
+```
+
+The `tryExecute` function takes the context of the current class or element as the first argument and the request as the second argument. Therefore, the above example can be used in any class or element that extends from either the [UmbController](https://apidocs.umbraco.com/v16/ui-api/interfaces/libs_controller-api.UmbController.html) or [UmbLitElement](https://apidocs.umbraco.com/v16/ui-api/classes/packages_core_lit-element.UmbLitElement.html) classes.
+
+{% hint style="info" %}
+The above example requires a host element illustrated by the use of `this`. This is typically a custom element that extends the `UmbLitElement` class.
+{% endhint %}
+
+It is recommended to always use the `tryExecute` function to wrap HTTP requests.
+
+### Disable Notifications
+
+The `tryExecute` function will automatically show error bubbles if a request fails. There may be valid cases where you want handle errors yourself. This could for instance be if you want to show a custom error message. You can disable the notifications by passing the `disableNotifications` option to the `tryExecute` function:
+
+```javascript
+tryExecute(this, request, {
+    disableNotifications: true,
+});
+```
+
+### Cancelling requests
+
+The `tryExecute` function also supports cancelling requests. This is useful if you want to cancel a request that is taking too long or if the user navigates away from the page. You can cancel a request by using the [AbortController API](https://developer.mozilla.org/en-US/docs/Web/API/AbortController). The `AbortController` API is a built-in API in modern browsers that allows you to cancel requests. You can use it directly with tryExecute:
+
+```javascript
+const abortController = new AbortController();
+
+// Cancel the request before starting it for illustration purposes
+abortController.abort();
+
+tryExecute(this, request, {
+    disableNotifications: true,
+    abortSignal: abortController.signal,
+});
+```