From d5b7b5882c1b646b5ad00a4f704e6b2bd9bff06e Mon Sep 17 00:00:00 2001
From: Dan Pastori <dan@521dimensions.com>
Date: Mon, 4 Apr 2022 01:10:10 -0700
Subject: [PATCH] docs: update data fetching for `$fetch` and refresh  (#3914)

---
 .../content/3.docs/1.usage/1.data-fetching.md | 40 ++++++++++++++++++-
 1 file changed, 39 insertions(+), 1 deletion(-)

diff --git a/docs/content/3.docs/1.usage/1.data-fetching.md b/docs/content/3.docs/1.usage/1.data-fetching.md
index 04c385f90e..8e81134e7c 100644
--- a/docs/content/3.docs/1.usage/1.data-fetching.md
+++ b/docs/content/3.docs/1.usage/1.data-fetching.md
@@ -169,7 +169,34 @@ watch(posts, (newPosts) => {
 </script>
 ```
 
-## `refreshNuxtData`
+## Refreshing Data
+
+Sometimes throughout the course of your user's page visit, you may need to refresh the data loaded from the API. This can happen if the user chooses to paginate, filter results, search, etc.
+
+You can make use of the `refresh()` method returned from the `useAsyncData()` composable to refresh the data with different query parameters:
+
+```vue
+<script setup>
+const page = ref(1);
+
+const { data:users, loading, refresh, error } = await useFetch(() => `users?page=${page.value}&take=6`, { baseURL: config.API_BASE_URL }
+);
+
+function previous(){
+  page.value--;
+  refresh();
+}
+
+function next() {
+  page.value++;
+  refresh();
+}
+</script>
+```
+
+The key to making this work is to call the `refresh()` method returned from the `useFetch()` composable when a query parameter has changed.
+
+### `refreshNuxtData`
 
 Invalidate the cache of `useAsyncData`, `useLazyAsyncData`, `useFetch` and `useLazyFetch` and trigger the refetch.
 
@@ -329,3 +356,14 @@ export default defineComponent({
   </header>
 </template>
 ```
+
+## Directly calling an API Endpoint
+
+There are instances where you may need to directly call the API. Nuxt 3 provides a globally available `$fetch` method using [unjs/ohmyfetch](https://github.com/unjs/ohmyfetch) (in addition to `fetch`)
+with the same API as the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch).
+
+Using `$fetch` has a number of benefits, including:
+
+It will handle 'smartly' making direct API calls if it's running on the server, or making a client-side call to your API if it's running on the client. (It can also handle calling third-party APIs.)
+
+Plus, it comes with convenience features including automatically parsing responses and stringifying data.