|
| 1 | +# Best practices when querying the API from UI components |
| 2 | + |
| 3 | +If you need to query the API from a component, there are several ways to do so. This document will help you decide which one to use and provide some best practices when doing so to keep the code clean and maintainable. |
| 4 | + |
| 5 | +## Choose the Right Approach |
| 6 | + |
| 7 | +When querying APIs in Vue components, consider the following approaches and their best practices: |
| 8 | + |
| 9 | +## 1. Prefer Composables over Stores over Direct API Calls |
| 10 | + |
| 11 | +### Composables |
| 12 | + |
| 13 | +- **What Are Composables?**: please read the official Vue documentation on composables [here](https://vuejs.org/guide/reusability/composables.html). |
| 14 | + |
| 15 | +If there is already a composable that takes care of the logic you need for accessing a particular resource in the API please use it or consider writing a new one. They provide a type-safe interface and a higher level of abstraction than the related Store or the API itself. They might rely on one or more Stores for caching and reactivity. |
| 16 | + |
| 17 | +### Stores |
| 18 | + |
| 19 | +- **Stores Explained**: Please read the official Vue documentation on State Management [here](https://vuejs.org/guide/scaling-up/state-management.html). |
| 20 | + |
| 21 | +If there is no Composable for the API endpoint you are using, try using a (Pinia) Store instead. Stores are type-safe and provide a reactive interface to the API. They can also be used to cache data, ensuring a single source of truth. |
| 22 | + |
| 23 | +- **Use Pinia Stores**: If you need to create a new Store, make sure to create a Pinia Store, and not a Vuex Store as Pinia will be the replacement for Vuex. Also, use [Composition API syntax over the Options API](https://vuejs.org/guide/extras/composition-api-faq.html) for increased readability, code organization, type inference, etc. |
| 24 | + |
| 25 | +### Direct API Calls |
| 26 | + |
| 27 | +- If the type of data you are querying should not be cached, or you just need to update or create new data, you can use the API directly. Make sure to use the **Fetcher** (see below) instead of Axios, as it provides a type-safe interface to the API along with some extra benefits. |
| 28 | + |
| 29 | +## 2. Prefer Fetcher over Axios (when possible) |
| 30 | + |
| 31 | +- **Use Fetcher with OpenAPI Specs**: If there is an OpenAPI spec for the API endpoint you are using (in other words, there is a FastAPI route defined in Galaxy), always use the Fetcher. It will provide you with a type-safe interface to the API. |
| 32 | + |
| 33 | +**Do** |
| 34 | + |
| 35 | +```typescript |
| 36 | +import { fetcher } from "@/api/schema"; |
| 37 | +const datasetsFetcher = fetcher.path("/api/dataset/{id}").method("get").create(); |
| 38 | + |
| 39 | +const { data: dataset } = await datasetsFetcher({ id: "testID" }); |
| 40 | +``` |
| 41 | + |
| 42 | +**Don't** |
| 43 | + |
| 44 | +```js |
| 45 | +import axios from "axios"; |
| 46 | +import { getAppRoot } from "onload/loadConfig"; |
| 47 | +import { rethrowSimple } from "utils/simple-error"; |
| 48 | + |
| 49 | +async getDataset(datasetId) { |
| 50 | + const url = `${getAppRoot()}api/datasets/${datasetId}`; |
| 51 | + try { |
| 52 | + const response = await axios.get(url); |
| 53 | + return response.data; |
| 54 | + } catch (e) { |
| 55 | + rethrowSimple(e); |
| 56 | + } |
| 57 | +} |
| 58 | + |
| 59 | +const dataset = await getDataset("testID"); |
| 60 | +``` |
| 61 | + |
| 62 | +> **Reason** |
| 63 | +> |
| 64 | +> The `fetcher` class provides a type-safe interface to the API, and is already configured to use the correct base URL and error handling. |
| 65 | +
|
| 66 | +## 3. Where to put your API queries? |
| 67 | + |
| 68 | +The short answer is: **it depends**. There are several factors to consider when deciding where to put your API queries: |
| 69 | + |
| 70 | +### Is the data you are querying related exclusively to a particular component? |
| 71 | + |
| 72 | +If so, you should put the query in the component itself. If not, you should consider putting it in a Composable or a Store. |
| 73 | + |
| 74 | +### Can the data be cached? |
| 75 | + |
| 76 | +If so, you should consider putting the query in a Store. If not, you should consider putting it in a Composable or the component itself. |
| 77 | + |
| 78 | +### Is the query going to be used in more than one place? |
| 79 | + |
| 80 | +If so, you should consider putting it under src/api/<resource>.ts and exporting it from there. This will allow you to reuse the query in multiple places specially if you need to do some extra processing of the data. Also it will help to keep track of what parts of the API are being used and where. |
| 81 | + |
| 82 | +### Should I use the `fetcher` directly or should I write a wrapper function? |
| 83 | + |
| 84 | +- If you **don't need to do any extra processing** of the data, you can use the `fetcher` directly. |
| 85 | +- If you **need to do some extra processing**, you should consider writing a wrapper function. Extra processing can be anything from transforming the data to adding extra parameters to the query or omitting some of them, handling conditional types in response data, etc. |
| 86 | +- Using a **wrapper function** will help in case we decide to replace the `fetcher` with something else in the future (as we are doing now with _Axios_). |
0 commit comments