From 9183875de6f3b721d127962ad98451dd6c01b9ac Mon Sep 17 00:00:00 2001
From: Macgregor Aubertin-Young <macgregor.aubertin-young@gov.bc.ca>
Date: Mon, 26 Aug 2024 12:15:27 -0700
Subject: [PATCH] improve itis service types & address PR comments

---
 api/src/paths/taxonomy/taxon/tsn/hierarchy.ts | 18 ++++++++++--------
 api/src/services/itis-service.ts              | 15 ++++++++++++---
 2 files changed, 22 insertions(+), 11 deletions(-)

diff --git a/api/src/paths/taxonomy/taxon/tsn/hierarchy.ts b/api/src/paths/taxonomy/taxon/tsn/hierarchy.ts
index 2d182946..33898d80 100644
--- a/api/src/paths/taxonomy/taxon/tsn/hierarchy.ts
+++ b/api/src/paths/taxonomy/taxon/tsn/hierarchy.ts
@@ -9,13 +9,9 @@ const defaultLog = getLogger('paths/taxonomy/taxon/tsn/hierarchy');
 export const GET: Operation = [getTaxonHierarchyByTSN()];
 
 GET.apiDoc = {
-  description: 'Get taxon records by TSN ids.',
+  description: 'Get taxon hierarchy information by TSN ids.',
   tags: ['taxon_id'],
-  security: [
-    {
-      Bearer: []
-    }
-  ],
+  security: [],
   parameters: [
     {
       description: 'Taxon TSN ids.',
@@ -44,12 +40,18 @@ GET.apiDoc = {
             items: {
               title: 'Species',
               type: 'object',
+              description: 'Taxon hierarchy response object with an array of parent TSNs',
               required: ['tsn', 'hierarchy'],
               properties: {
                 tsn: {
                   type: 'integer'
                 },
-                hierarchy: { type: 'array', items: { type: 'integer' } }
+                hierarchy: {
+                  type: 'array',
+                  description:
+                    'Array of parent TSNs in descending order, where the highest-ranking parent is first and the TSN for which the hierarchy was requested is last.',
+                  items: { type: 'integer' }
+                }
               },
               additionalProperties: false
             }
@@ -83,7 +85,7 @@ export function getTaxonHierarchyByTSN(): RequestHandler {
 
     const connection = getAPIUserDBConnection();
 
-    const tsnIds: number[] = (req.query.tsn as (string | number)[]).map(Number);
+    const tsnIds: number[] = (req.query.tsn as string[]).map(Number);
 
     try {
       await connection.open();
diff --git a/api/src/services/itis-service.ts b/api/src/services/itis-service.ts
index 5378fdf2..b3f95117 100644
--- a/api/src/services/itis-service.ts
+++ b/api/src/services/itis-service.ts
@@ -27,6 +27,15 @@ export type TSNWithHierarchy = {
   hierarchy: number[];
 };
 
+/**
+ * Generic base type for the ITIS Solr service
+ */
+type ItisSolrResponseBase<T> = {
+  response: {
+    docs: T;
+  };
+};
+
 /**
  * Service for retrieving and processing taxonomic data from the Integrated Taxonomic Information System (ITIS).
  *
@@ -48,7 +57,7 @@ export class ItisService {
 
     defaultLog.debug({ label: 'searchItisByTerm', message: 'url', url });
 
-    const response = await axios.get(url);
+    const response = await axios.get<ItisSolrResponseBase<ItisSolrSearchResponse[]>>(url);
 
     if (!response.data || !response.data.response || !response.data.response.docs) {
       return [];
@@ -76,7 +85,7 @@ export class ItisService {
 
     defaultLog.debug({ label: 'searchItisByTSN', message: 'url', url });
 
-    const response = await axios.get(url);
+    const response = await axios.get<ItisSolrResponseBase<ItisSolrSearchResponse[]>>(url);
 
     if (!response.data || !response.data.response || !response.data.response.docs) {
       return [];
@@ -97,7 +106,7 @@ export class ItisService {
 
     defaultLog.debug({ label: 'getHierarchyForTSNs', message: 'url', url });
 
-    const response = await axios.get(url);
+    const response = await axios.get<ItisSolrResponseBase<ItisSolrSearchResponseHierarchy[]>>(url);
 
     if (!response.data || !response.data.response || !response.data.response.docs) {
       return [];