refactor!: drop support for single API endpoint

docs/.vitepress/config.ts

@@ -88,10 +88,11 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
     {
       text: 'FAQ',
       items: [
-        { text: 'How to Track Errors?', link: '/guide/faq-how-to-track-errors' },
+        { text: 'How to Track Errors', link: '/guide/faq-how-to-track-errors' },
       ],
     },
     { text: 'Playground', link: 'https://github.com/johannschopplich/nuxt-api-party/tree/main/playground' },
+    { text: 'Migration', link: '/guide/migration' },
   ]
 }
 

docs/api/api-party.md

@@ -1,7 +1,7 @@
 # `$apiParty`
 
 ::: info
-`$apiParty` is a placeholder name. Composables are generated based on your endpoint API names. For example, if you were to call an endpoint `jsonPlaceholder`, the composable will be called `$jsonPlaceholder`.
+`$apiParty` is a placeholder used as an example in the documentation. The composable is generated based on your API endpoint ID. For example, if you were to call an endpoint `jsonPlaceholder`, the composable will be called `$jsonPlaceholder`.
 :::
 
 Returns the raw response of the API endpoint. Intended for actions inside methods, e.g. when sending form data to the API when clicking a submit button.

docs/api/index.md

@@ -8,11 +8,12 @@
 - [`useApiPartyData`](/api/use-api-party-data) – Returns multiple values similar to [`useFetch`](https://nuxt.com/docs/api/composables/use-fetch)
 
 ::: info
-`$apiParty` and `useApiPartyData` are placeholder names. They are used in the examples below to demonstrate the composables' return values. For each of your API endpoints, both composable types are generated based on the name of the endpoint.
+`$apiParty` and `useApiPartyData` are placeholders. They are used as examples in the documentation. The actual composables are generated based on your API endpoint ID.
 :::
 
 ## Dynamic Composables
 
-Based on the name of your API endpoint, the generated composables are customized. For example, if you were to call your API `jsonPlaceholder`, the generated composables are:
+The composables are generated based on your API endpoint ID. For example, if you were to call your API `jsonPlaceholder`, the generated composables are:
+
 - `$jsonPlaceholder`
 - `useJsonPlaceholderData`

docs/api/use-api-party-data.md

@@ -1,7 +1,7 @@
 # `useApiPartyData`
 
 ::: info
-`useApiPartyData` is a placeholder name. Composables are generated based on your endpoint API names. For example, if you were to call an endpoint `jsonPlaceholder`, the composable will be called `useJsonPlaceholderData`.
+`useApiPartyData` is a placeholder used as an example in the documentation. The composable is generated based on your API endpoint ID. For example, if you were to call an endpoint `jsonPlaceholder`, the composable will be called `useJsonPlaceholderData`.
 :::
 
 Returns the raw response of the API endpoint. Intended for data which requires reactive updates, e.g. when using the data in a template.
@@ -71,34 +71,29 @@ const { data, pending, error, refresh } = await usePartyData('posts/1')
 </template>
 ```
 
-**Full example including all parameters**
+**Extended example**
 
 ```vue
 <script setup lang="ts">
 const postId = ref(1)
+
 const { data, pending, refresh, error } = await usePartyData('comments', {
   // Whether to resolve the async function after loading the route, instead of blocking client-side navigation (defaults to `false`)
-  lazy: false,
+  lazy: true,
   // A factory function to set the default value of the data, before the async function resolves - particularly useful with the `lazy: true` option
   default: () => ({
-    foo: 'bar'
+    title: ''
   }),
-  // Whether to fetch the data on the server (defaults to `true`)
-  server: true,
   // A function that can be used to alter handler function result after resolving
   transform: res => res,
-  // When set to `false`, will prevent the request from firing immediately. (defaults to `true`)
-  immediate: true,
-  // Watch reactive sources to auto-refresh
-  watch: [],
   // Custom query parameters to be added to the request, can be reactive
   query: computed(() => ({
     postId: postId.value
   })),
   // Custom headers to be sent with the request
   headers: {
     'X-Foo': 'bar'
-  }
+  },
 })
 </script>
 

docs/config/index.md

@@ -7,16 +7,25 @@ Adapt `nuxt-api-party` to your needs with the following options in your `nuxt.co
 export default defineNuxtConfig({
   modules: ['nuxt-api-party'],
   apiParty: {
-    // ... your options
+    endpoints: {
+      // ... your API endpoints
+    }
   }
 })
 ```
 
 ## `apiParty.endpoints`
 
-Main module configuration for your API endpoints.
+Main module configuration for your API endpoints. Each key represents an endpoint ID, which is used to generate the composables. The value is an object with the following properties:
 
-This will generate multiple API composables for the given endpoint configurations.
+- `url`: The URL of the API endpoint
+- `token`: The API token to use for the endpoint (optional)
+- `query`: The query parameters to use for the endpoint (optional)
+- `headers`: The headers to use for the endpoint (optional)
+
+::: info
+The composables are generated based on your API endpoint ID. For example, if you were to call an endpoint `jsonPlaceholder`, the composables will be called `useJsonPlaceholderData` and `$jsonPlaceholder`.
+:::
 
 Default value: `{}`
 
@@ -49,96 +58,11 @@ export default defineNuxtConfig({
       cms: {
         url: process.env.CMS_API_BASE_URL!,
         headers: {
-          'Custom-Api-Header': 'foo',
+          'X-Foo': 'bar',
           'Authorization': `Basic ${Buffer.from(`${process.env.CMS_API_USERNAME}:${process.env.CMS_API_PASSWORD}`).toString('base64')}`
         }
       }
     }
   }
 })
 ```
-
-## `apiParty.name`
-
-::: tip
-Use this option if you only have a single API endpoint.
-:::
-
-API name for your API endpoint.
-
-Default value: `undefined`
-
-**Type**
-
-`string | undefined`
-
-## `apiParty.url`
-
-::: tip
-Use this option if you only have a single API endpoint.
-:::
-
-API base URL your API endpoint.
-
-Default value: `process.env.API_PARTY_BASE_URL`
-
-**Type**
-
-`string | undefined`
-
-## `apiParty.token`
-
-::: tip
-Use this option if you only have a single API endpoint.
-:::
-
-Optional API bearer token for your API endpoint.
-
-You can set a custom header with the `headers` module option instead.
-
-Default value: `process.env.API_PARTY_TOKEN`
-
-**Type**
-
-`string | undefined`
-
-## `apiParty.query`
-
-::: info
-Only for single API endpoint usage. Not applied if you use the `endpoints` module option.
-:::
-
-Custom query parameters sent with every API request.
-
-Default value: `undefined`
-
-**Type**
-
-`Record<string, QueryValue | QueryValue[]> | undefined`
-
-## `apiParty.headers`
-
-::: info
-Only for single API endpoint usage. Not applied if you use the `endpoints` module option.
-:::
-
-Custom headers sent with every API request. Add authorization headers if you want to use a custom authorization method.
-
-Default value: `undefined`
-
-**Type**
-
-`Record<string, string> | undefined`
-
-**Example**
-
-```ts
-export default defineNuxtConfig({
-  apiParty: {
-    headers: {
-      'Custom-Api-Header': 'foo',
-      'Authorization': `Basic ${Buffer.from('foo:bar').toString('base64')}`
-    }
-  }
-})
-```

docs/guide/faq-how-to-track-errors.md

@@ -1,4 +1,4 @@
-# How to Track Errors?
+# How to Track Errors
 
 Although the idea of this module is to mask your real API by creating a Nuxt server proxy, `nuxt-api-party` will forward error responses to the client if your API fails to deliver, including:
 

docs/guide/getting-started.md

@@ -29,7 +29,12 @@ export default defineNuxtConfig({
 
 ## Step 3: Set up the API endpoints
 
-Prepare your first API connection by setting an endpoint object with the following properties for the `apiParty` module option:
+Prepare your first API connection by setting an endpoint object. Each key represents an endpoint ID, which is used to generate the composables. The value is an object with the following properties:
+
+- `url`: The URL of the API endpoint
+- `token`: The API token to use for the endpoint (optional)
+- `query`: The query parameters to use for the endpoint (optional)
+- `headers`: The headers to use for the endpoint (optional)
 
 ```ts
 // `nuxt.config.ts`
@@ -50,13 +55,13 @@ export default defineNuxtConfig({
 })
 ```
 
-If you were to call your API `jsonPlaceholder`, the generated composables are:
+For the API endpoint `jsonPlaceholder` above, the following composables are generated:
 
 - `$jsonPlaceholder` – Returns the response data, similar to [`$fetch`](https://nuxt.com/docs/api/utils/dollarfetch#fetch)
 - `useJsonPlaceholderData` – Returns [multiple values](/api/use-api-party-data.html#return-values) similar to [`useFetch`](https://nuxt.com/docs/api/composables/use-fetch)
 
 ::: tip
-You can connect as many APIs as you want, just add them to the `endpoints` object.
+Connect to as many API endpoints as you like. Each endpoint will generate two composables.
 :::
 
 ### Runtime Config

docs/guide/migration.md

@@ -0,0 +1,48 @@
+# Migration
+
+## v0.10.0
+
+Support for the single API endpoint has been removed to keep the module simple and focused. Migration is fairly straightforward by moving your API configuration into the `endpoints` object:
+
+```diff
+export default defineNuxtConfig({
+  apiParty: {
+-   name: 'myApi',
+-    url: '<your-api-url>',
+-    token: '<your-api-token>',
+-    query: {},
+-    headers: {},
++    endpoints: {
++      myApi: {
++        url: '<your-api-url>',
++        token: '<your-api-token>',
++        query: {},
++        headers: {},
++      },
+    },
+  }
+})
+```
+
+If you previously used the following environment variables in your project's `.env` file:
+
+```bash
+API_PARTY_BASE_URL=your-api-url
+# Optionally, add a bearer token
+API_PARTY_TOKEN=your-api-token
+```
+
+You can now reference them in your API configuration:
+
+```ts
+export default defineNuxtConfig({
+  apiParty: {
+    endpoints: {
+      myApi: {
+        url: process.env.API_PARTY_BASE_URL!,
+        token: process.env.API_PARTY_TOKEN!,
+      },
+    },
+  }
+})
+```

docs/index.md

@@ -26,7 +26,7 @@ hero:
 features:
   - title: Dynamic composable names
     icon: 🪅
-    details: Auto-generated composables for each API endpoint
+    details: Auto-generated composables for each API endpoint.
   - title: Protected API credentials
     icon: 🔒
     details: A Nuxt server route proxies your requests. No CORS issues!