Merge pull request #16847 from davelopez/refactor_client_api_modules

Refactor client API packages

.github/labeler.yml

@@ -63,7 +63,7 @@ area/toolshed:
   - lib/toolshed/**/*
   - templates/webapps/tool_shed/**/*
 area/UI-UX:
-  - all: ["client/src/**/*", "!client/src/schema/schema.ts"]
+  - all: ["client/src/**/*", "!client/src/api/schema/schema.ts"]
     any: ["templates/**/*"]
 area/util:
   - lib/galaxy/util/**/*

.github/workflows/lint_openapi_schema.yml

@@ -57,7 +57,7 @@ jobs:
       - name: Check for changes
         run: |
           if [[ `git status --porcelain` ]]; then
-            echo "Rebuilding client/src/schema/schema.ts resulted in changes, run 'make update-client-api-schema' and commit results"
+            echo "Rebuilding client/src/api/schema/schema.ts resulted in changes, run 'make update-client-api-schema' and commit results"
             exit 1
           fi
         working-directory: 'galaxy root'

Makefile

@@ -189,7 +189,7 @@ remove-api-schema:
 	rm _shed_schema.yaml
 
 update-client-api-schema: client-node-deps build-api-schema
-	$(IN_VENV) cd client && node openapi_to_schema.mjs ../_schema.yaml > src/schema/schema.ts && npx prettier --write src/schema/schema.ts
+	$(IN_VENV) cd client && node openapi_to_schema.mjs ../_schema.yaml > src/api/schema/schema.ts && npx prettier --write src/api/schema/schema.ts
 	$(IN_VENV) cd client && node openapi_to_schema.mjs ../_shed_schema.yaml > ../lib/tool_shed/webapp/frontend/src/schema/schema.ts && npx prettier --write ../lib/tool_shed/webapp/frontend/src/schema/schema.ts
 	$(MAKE) remove-api-schema
 

client/docs/querying-the-api.md

@@ -0,0 +1,86 @@
+# Best practices when querying the API from UI components
+
+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.
+
+## Choose the Right Approach
+
+When querying APIs in Vue components, consider the following approaches and their best practices:
+
+## 1. Prefer Composables over Stores over Direct API Calls
+
+### Composables
+
+-   **What Are Composables?**: please read the official Vue documentation on composables [here](https://vuejs.org/guide/reusability/composables.html).
+
+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.
+
+### Stores
+
+-   **Stores Explained**: Please read the official Vue documentation on State Management [here](https://vuejs.org/guide/scaling-up/state-management.html).
+
+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.
+
+-   **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.
+
+### Direct API Calls
+
+-   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.
+
+## 2. Prefer Fetcher over Axios (when possible)
+
+-   **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.
+
+**Do**
+
+```typescript
+import { fetcher } from "@/api/schema";
+const datasetsFetcher = fetcher.path("/api/dataset/{id}").method("get").create();
+
+const { data: dataset } = await datasetsFetcher({ id: "testID" });
+```
+
+**Don't**
+
+```js
+import axios from "axios";
+import { getAppRoot } from "onload/loadConfig";
+import { rethrowSimple } from "utils/simple-error";
+
+async getDataset(datasetId) {
+    const url = `${getAppRoot()}api/datasets/${datasetId}`;
+    try {
+        const response = await axios.get(url);
+        return response.data;
+    } catch (e) {
+        rethrowSimple(e);
+    }
+}
+
+const dataset = await getDataset("testID");
+```
+
+> **Reason**
+>
+> The `fetcher` class provides a type-safe interface to the API, and is already configured to use the correct base URL and error handling.
+
+## 3. Where to put your API queries?
+
+The short answer is: **it depends**. There are several factors to consider when deciding where to put your API queries:
+
+### Is the data you are querying related exclusively to a particular component?
+
+If so, you should put the query in the component itself. If not, you should consider putting it in a Composable or a Store.
+
+### Can the data be cached?
+
+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.
+
+### Is the query going to be used in more than one place?
+
+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.
+
+### Should I use the `fetcher` directly or should I write a wrapper function?
+
+-   If you **don't need to do any extra processing** of the data, you can use the `fetcher` directly.
+-   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.
+-   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_).

client/src/stores/services/datasetCollection.service.ts → client/src/api/datasetCollections.ts

@@ -1,13 +1,16 @@
-import { fetcher } from "@/schema";
-
-import { CollectionEntry, DatasetCollectionAttributes, DCESummary, HDCADetailed, isHDCA } from ".";
+import { CollectionEntry, DatasetCollectionAttributes, DCESummary, HDCADetailed, isHDCA } from "@/api";
+import { fetcher } from "@/api/schema";
 
 const DEFAULT_LIMIT = 50;
 
 const getCollectionDetails = fetcher.path("/api/dataset_collections/{id}").method("get").create();
 
-export async function fetchCollectionDetails(params: { hdcaId: string }): Promise<HDCADetailed> {
-    const { data } = await getCollectionDetails({ id: params.hdcaId });
+/**
+ * Fetches the details of a collection.
+ * @param params.id The ID of the collection (HDCA) to fetch.
+ */
+export async function fetchCollectionDetails(params: { id: string }): Promise<HDCADetailed> {
+    const { data } = await getCollectionDetails({ id: params.id });
     return data;
 }
 

client/src/api/datasets.ts

@@ -0,0 +1,89 @@
+import type { FetchArgType } from "openapi-typescript-fetch";
+
+import { DatasetDetails } from "@/api";
+import { fetcher } from "@/api/schema";
+import { withPrefix } from "@/utils/redirect";
+
+export const datasetsFetcher = fetcher.path("/api/datasets").method("get").create();
+
+type GetDatasetsApiOptions = FetchArgType<typeof datasetsFetcher>;
+type GetDatasetsQuery = Pick<GetDatasetsApiOptions, "limit" | "offset">;
+// custom interface for how we use getDatasets
+interface GetDatasetsOptions extends GetDatasetsQuery {
+    sortBy?: string;
+    sortDesc?: string;
+    query?: string;
+}
+
+/** Datasets request helper **/
+export async function getDatasets(options: GetDatasetsOptions = {}) {
+    const params: GetDatasetsApiOptions = {};
+    if (options.sortBy) {
+        const sortPrefix = options.sortDesc ? "-dsc" : "-asc";
+        params.order = `${options.sortBy}${sortPrefix}`;
+    }
+    if (options.limit) {
+        params.limit = options.limit;
+    }
+    if (options.offset) {
+        params.offset = options.offset;
+    }
+    if (options.query) {
+        params.q = ["name-contains"];
+        params.qv = [options.query];
+    }
+    const { data } = await datasetsFetcher(params);
+    return data;
+}
+
+const getDataset = fetcher.path("/api/datasets/{dataset_id}").method("get").create();
+
+export async function fetchDatasetDetails(params: { id: string }): Promise<DatasetDetails> {
+    const { data } = await getDataset({ dataset_id: params.id, view: "detailed" });
+    // We know that the server will return a DatasetDetails object because of the view parameter
+    // but the type system doesn't, so we have to cast it.
+    return data as unknown as DatasetDetails;
+}
+
+const updateHistoryDataset = fetcher.path("/api/histories/{history_id}/contents/{type}s/{id}").method("put").create();
+
+export async function undeleteHistoryDataset(historyId: string, datasetId: string) {
+    const { data } = await updateHistoryDataset({
+        history_id: historyId,
+        id: datasetId,
+        type: "dataset",
+        deleted: false,
+    });
+    return data;
+}
+
+const deleteHistoryDataset = fetcher
+    .path("/api/histories/{history_id}/contents/{type}s/{id}")
+    .method("delete")
+    .create();
+
+export async function purgeHistoryDataset(historyId: string, datasetId: string) {
+    const { data } = await deleteHistoryDataset({ history_id: historyId, id: datasetId, type: "dataset", purge: true });
+    return data;
+}
+
+const datasetCopy = fetcher.path("/api/histories/{history_id}/contents/{type}s").method("post").create();
+type HistoryContentsArgs = FetchArgType<typeof datasetCopy>;
+export async function copyDataset(
+    datasetId: HistoryContentsArgs["content"],
+    historyId: HistoryContentsArgs["history_id"],
+    type: HistoryContentsArgs["type"] = "dataset",
+    source: HistoryContentsArgs["source"] = "hda"
+) {
+    const response = await datasetCopy({
+        history_id: historyId,
+        type,
+        source: source,
+        content: datasetId,
+    });
+    return response.data;
+}
+
+export function getCompositeDatasetLink(historyDatasetId: string, path: string) {
+    return withPrefix(`/api/datasets/${historyDatasetId}/display?filename=${path}`);
+}

client/src/api/datatypes.ts

@@ -0,0 +1,13 @@
+import { fetcher } from "@/api/schema";
+
+export const datatypesFetcher = fetcher.path("/api/datatypes").method("get").create();
+
+export const edamFormatsFetcher = fetcher.path("/api/datatypes/edam_formats/detailed").method("get").create();
+export const edamDataFetcher = fetcher.path("/api/datatypes/edam_data/detailed").method("get").create();
+
+const typesAndMappingsFetcher = fetcher.path("/api/datatypes/types_and_mapping").method("get").create();
+
+export async function fetchDatatypesAndMappings(upload_only = true) {
+    const { data } = await typesAndMappingsFetcher({ upload_only });
+    return data;
+}

client/src/api/dbKeys.ts

@@ -0,0 +1,8 @@
+/**
+ * Historically, this API was used to get the list of genomes that were available
+ * but now it is used to get the list of more generic "dbkeys".
+ */
+
+import { fetcher } from "@/api/schema";
+
+export const dbKeysFetcher = fetcher.path("/api/genomes").method("get").create();

client/src/api/groups.ts

@@ -0,0 +1,9 @@
+import axios from "axios";
+
+import { components } from "@/api/schema";
+
+type GroupModel = components["schemas"]["GroupModel"];
+export async function getAllGroups(): Promise<GroupModel[]> {
+    const { data } = await axios.get("/api/groups");
+    return data;
+}

client/src/stores/services/historyArchive.services.ts → client/src/api/histories.archived.ts

@@ -1,6 +1,6 @@
 import type { FetchArgType } from "openapi-typescript-fetch";
 
-import { type components, fetcher } from "@/schema";
+import { type components, fetcher } from "@/api/schema";
 
 export type ArchivedHistorySummary = components["schemas"]["ArchivedHistorySummary"];
 export type ArchivedHistoryDetailed = components["schemas"]["ArchivedHistoryDetailed"];
@@ -55,7 +55,7 @@ export async function fetchArchivedHistories(
     };
 }
 
-const archiveHistory = fetcher.path("/api/histories/{history_id}/archive").method("post").create();
+const postArchiveHistory = fetcher.path("/api/histories/{history_id}/archive").method("post").create();
 
 /**
  * Archive a history.
@@ -64,20 +64,20 @@ const archiveHistory = fetcher.path("/api/histories/{history_id}/archive").metho
  * @param purgeHistory Whether to purge the history after archiving. Can only be used in combination with an archive export record.
  * @returns The archived history summary.
  */
-export async function archiveHistoryById(
+export async function archiveHistory(
     historyId: string,
     archiveExportId?: string,
     purgeHistory?: boolean
 ): Promise<ArchivedHistorySummary> {
-    const { data } = await archiveHistory({
+    const { data } = await postArchiveHistory({
         history_id: historyId,
         archive_export_id: archiveExportId,
         purge_history: purgeHistory,
     });
     return data as ArchivedHistorySummary;
 }
 
-const unarchiveHistory = fetcher
+const putUnarchiveHistory = fetcher
     .path("/api/histories/{history_id}/archive/restore")
     .method("put")
     // @ts-ignore: workaround for optional query parameters in PUT. More info here https://github.com/ajaishankar/openapi-typescript-fetch/pull/55
@@ -89,8 +89,8 @@ const unarchiveHistory = fetcher
  * @param force Whether to force un-archiving for purged histories.
  * @returns The restored history summary.
  */
-export async function unarchiveHistoryById(historyId: string, force?: boolean): Promise<ArchivedHistorySummary> {
-    const { data } = await unarchiveHistory({ history_id: historyId, force });
+export async function unarchiveHistory(historyId: string, force?: boolean): Promise<ArchivedHistorySummary> {
+    const { data } = await putUnarchiveHistory({ history_id: historyId, force });
     return data as ArchivedHistorySummary;
 }
 
@@ -102,7 +102,7 @@ const reimportHistoryFromStore = fetcher.path("/api/histories/from_store_async")
  * @param archivedHistory The archived history to reimport. It must have an associated export record.
  * @returns The async task result summary to track the reimport progress.
  */
-export async function reimportHistoryFromExportRecordAsync(
+export async function reimportArchivedHistoryFromExportRecord(
     archivedHistory: ArchivedHistorySummary
 ): Promise<AsyncTaskResultSummary> {
     if (!archivedHistory.export_record_data) {

client/src/components/History/Export/services.ts → client/src/api/histories.export.ts

@@ -1,8 +1,8 @@
+import type { components } from "@/api/schema";
+import { fetcher } from "@/api/schema";
 import type { ObjectExportTaskResponse } from "@/components/Common/models/exportRecordModel";
 import { ExportRecordModel } from "@/components/Common/models/exportRecordModel";
 import { DEFAULT_EXPORT_PARAMS } from "@/composables/shortTermStorage";
-import type { components } from "@/schema";
-import { fetcher } from "@/schema";
 
 type ModelStoreFormat = components["schemas"]["ModelStoreFormat"];
 
@@ -24,7 +24,7 @@ export const AVAILABLE_EXPORT_FORMATS: { id: ModelStoreFormat; name: string }[]
  * @param params query and pagination params
  * @returns a promise with a list of export records associated with the given history.
  */
-export async function getExportRecords(historyId: string) {
+export async function fetchHistoryExportRecords(historyId: string) {
     const response = await _getExportRecords(
         {
             history_id: historyId,
@@ -46,7 +46,7 @@ export async function getExportRecords(historyId: string) {
  * @param exportParams additional parameters to configure the export
  * @returns A promise with the request response
  */
-export async function exportToFileSource(
+export async function exportHistoryToFileSource(
     historyId: string,
     exportDirectory: string,
     fileName: string,

client/src/api/histories.ts

@@ -0,0 +1,6 @@
+import { fetcher } from "@/api/schema";
+
+export const historiesFetcher = fetcher.path("/api/histories").method("get").create();
+export const archivedHistoriesFetcher = fetcher.path("/api/histories/archived").method("get").create();
+export const undeleteHistory = fetcher.path("/api/histories/deleted/{history_id}/undelete").method("post").create();
+export const purgeHistory = fetcher.path("/api/histories/{history_id}").method("delete").create();

client/src/stores/services/index.ts → client/src/api/index.ts

@@ -1,4 +1,16 @@
-import { components } from "@/schema";
+/** Contains type alias and definitions related to Galaxy API models. */
+
+import { components } from "@/api/schema";
+
+/**
+ * Contains minimal information about a History.
+ */
+export type HistorySummary = components["schemas"]["HistorySummary"];
+
+/**
+ * Contains additional details about a History.
+ */
+export type HistoryDetailed = components["schemas"]["HistoryDetailed"];
 
 /**
  * Contains minimal information about a HistoryContentItem.

client/src/api/jobs.ts

@@ -0,0 +1,4 @@
+import { fetcher } from "@/api/schema";
+
+export const jobLockStatus = fetcher.path("/api/job_lock").method("get").create();
+export const jobLockUpdate = fetcher.path("/api/job_lock").method("put").create();