ref(tsc): refactor self-contained endpoints that need response headers to apiOptions (#112347)

as discussed in last week’s TSC, we need to start moving endpoints over
to `apiOptions` so that we can re-use caches.

the quickest win would be to implement `useApiQuery` with `apiOptions`
internally, and to get there, we need to migrate endpoints that now need
`getResponseHeader` over to `apiOptions` because those headers are
exposed differently.

this PR takes the first couple of endpoints that are (mostly)
self-contained (no other usages of the url found) and moves them over.

I’ve also exposed `selectJsonWithHeaders` because the default impl only
selects `json` without `headers`.

I plan to tackle the other occurrences with an endpoint-by-endpoint
approach, as we need to identify all places where an endpoint is used
(e.g. `invalidateQueries` or `getApiQueryData` or `setApiQueryData`) and
migrate them together.

Author: TkDodo

static/AGENTS.md

@@ -60,6 +60,32 @@ const query = useQuery(
 
 Existing code might use `useApiQuery` from `sentry/utils/queryClient` — prefer `apiOptions` for new code.
 
+#### Accessing response headers (pagination, hit counts)
+
+By default, `apiOptions` selects only the JSON body from the response. If you need response headers (e.g., `Link` for pagination or `X-Hits` / `X-Max-Hits` for total counts), override `select` with `selectJsonWithHeaders`:
+
+```typescript
+import {useQuery} from '@tanstack/react-query';
+import {apiOptions, selectJsonWithHeaders} from 'sentry/utils/api/apiOptions';
+
+const {data} = useQuery({
+  ...apiOptions.as<Item[]>()('/organizations/$organizationIdOrSlug/items/', {
+    path: {organizationIdOrSlug: organization.slug},
+    query: {cursor, per_page: 25},
+    staleTime: 0,
+  }),
+  select: selectJsonWithHeaders,
+});
+
+// data is ApiResponse<Item[]> — an object with `json` and `headers`
+const items = data?.json ?? [];
+const pageLinks = data?.headers.Link; // string | undefined
+const totalHits = data?.headers['X-Hits']; // number | undefined
+const maxHits = data?.headers['X-Max-Hits']; // number | undefined
+```
+
+Note that `X-Hits` and `X-Max-Hits` are already parsed to `number | undefined` — no `parseInt` needed.
+
 ## General Frontend Rules
 
 1. NO new Reflux stores

static/app/utils/api/apiOptions.ts

@@ -23,6 +23,12 @@ type PathParamOptions<TApiPath extends string> =
     ? {path?: never}
     : {path: Record<ExtractPathParams<TApiPath>, string | number> | SkipToken};
 
+const selectJson = <TData>(data: ApiResponse<TData>) => data.json;
+
+export const selectJsonWithHeaders = <TData>(
+  data: ApiResponse<TData>
+): ApiResponse<TData> => data;
+
 function _apiOptions<
   TManualData = never,
   TApiPath extends KnownApiUrls = KnownApiUrls,
@@ -46,7 +52,7 @@ function _apiOptions<
     queryFn: pathParams === skipToken ? skipToken : apiFetch<TActualData>,
     enabled: pathParams !== skipToken,
     staleTime,
-    select: data => data.json,
+    select: selectJson,
   });
 }
 
@@ -86,6 +92,50 @@ function _apiOptionsInfinite<
   });
 }
 
+/**
+ * Type-safe factory for TanStack Query options that hit Sentry API endpoints.
+ *
+ * By default, `select` extracts the JSON body. To also access response headers
+ * (e.g. `Link` for pagination), override with `selectJsonWithHeaders`.
+ *
+ * @example Basic usage
+ * ```ts
+ * const query = useQuery(
+ *   apiOptions.as<Project[]>()('/organizations/$organizationIdOrSlug/projects/', {
+ *     path: {organizationIdOrSlug: organization.slug},
+ *     staleTime: 30_000,
+ *   })
+ * );
+ * // query.data is Project[]
+ * ```
+ *
+ * @example Conditional fetching
+ * ```ts
+ * const query = useQuery(
+ *   apiOptions.as<Project>()('/organizations/$organizationIdOrSlug/projects/$projectIdOrSlug/', {
+ *     path: projectSlug
+ *       ? {organizationIdOrSlug: organization.slug, projectIdOrSlug: projectSlug}
+ *       : skipToken,
+ *     staleTime: 30_000,
+ *   })
+ * );
+ * ```
+ *
+ * @example With response headers (pagination)
+ * ```ts
+ * const {data} = useQuery({
+ *   ...apiOptions.as<Item[]>()('/organizations/$organizationIdOrSlug/items/', {
+ *     path: {organizationIdOrSlug: organization.slug},
+ *     query: {cursor, per_page: 25},
+ *     staleTime: 0,
+ *   }),
+ *   select: selectJsonWithHeaders,
+ * });
+ * // data is ApiResponse<Item[]>
+ * const items = data?.json ?? [];
+ * const pageLinks = data?.headers.Link;
+ * ```
+ */
 export const apiOptions = {
   as:
     <TManualData>() =>

static/app/utils/replays/hooks/useDeadRageSelectors.tsx

@@ -1,5 +1,6 @@
-import {getApiUrl} from 'sentry/utils/api/getApiUrl';
-import {useApiQuery} from 'sentry/utils/queryClient';
+import {useQuery} from '@tanstack/react-query';
+
+import {apiOptions, selectJsonWithHeaders} from 'sentry/utils/api/apiOptions';
 import {decodeList, decodeScalar} from 'sentry/utils/queryString';
 import {hydratedSelectorData} from 'sentry/utils/replays/hydrateSelectorData';
 import {useLocation} from 'sentry/utils/useLocation';
@@ -14,37 +15,37 @@ export function useDeadRageSelectors(params: DeadRageSelectorQueryParams) {
   const location = useLocation();
   const {query} = location;
 
-  const {isPending, isError, error, data, getResponseHeader} =
-    useApiQuery<DeadRageSelectorListResponse>(
-      [
-        getApiUrl('/organizations/$organizationIdOrSlug/replay-selectors/', {
-          path: {organizationIdOrSlug: organization.slug},
-        }),
-        {
-          query: {
-            query: '!count_dead_clicks:0',
-            cursor: params.cursor,
-            environment: decodeList(query.environment),
-            project: query.project,
-            statsPeriod: query.statsPeriod,
-            start: decodeScalar(query.start),
-            end: decodeScalar(query.end),
-            per_page: params.per_page,
-            sort: query[params.prefix + 'sort'] ?? params.sort,
-          },
+  const {isPending, isError, error, data} = useQuery({
+    ...apiOptions.as<DeadRageSelectorListResponse>()(
+      '/organizations/$organizationIdOrSlug/replay-selectors/',
+      {
+        path: {organizationIdOrSlug: organization.slug},
+        query: {
+          query: '!count_dead_clicks:0',
+          cursor: params.cursor,
+          environment: decodeList(query.environment),
+          project: query.project,
+          statsPeriod: query.statsPeriod,
+          start: decodeScalar(query.start),
+          end: decodeScalar(query.end),
+          per_page: params.per_page,
+          sort: query[params.prefix + 'sort'] ?? params.sort,
         },
-      ],
-      {staleTime: Infinity, enabled: params.enabled}
-    );
+        staleTime: Infinity,
+      }
+    ),
+    select: selectJsonWithHeaders,
+    enabled: params.enabled,
+  });
 
   return {
     isLoading: isPending,
     isError,
     error,
     data: hydratedSelectorData(
-      data ? data.data : [],
+      data ? data.json.data : [],
       params.isWidgetData ? params.sort?.replace(/^-/, '') : null
     ),
-    pageLinks: getResponseHeader?.('Link') ?? undefined,
+    pageLinks: data?.headers.Link,
   };
 }

static/app/views/alerts/list/rules/alertRulesList.tsx

@@ -1,5 +1,6 @@
 import {Fragment} from 'react';
 import styled from '@emotion/styled';
+import {useQuery} from '@tanstack/react-query';
 import type {Location} from 'history';
 
 import {Alert} from '@sentry/scraps/alert';
@@ -22,12 +23,11 @@ import {IconArrow} from 'sentry/icons';
 import {t} from 'sentry/locale';
 import type {Project} from 'sentry/types/project';
 import {defined} from 'sentry/utils';
-import {getApiUrl} from 'sentry/utils/api/getApiUrl';
+import {apiOptions, selectJsonWithHeaders} from 'sentry/utils/api/apiOptions';
 import {uniq} from 'sentry/utils/array/uniq';
 import {VisuallyCompleteWithData} from 'sentry/utils/performanceForSentry';
 import {Projects} from 'sentry/utils/projects';
-import type {ApiQueryKey} from 'sentry/utils/queryClient';
-import {setApiQueryData, useApiQuery, useQueryClient} from 'sentry/utils/queryClient';
+import {useQueryClient} from 'sentry/utils/queryClient';
 import {useRouteAnalyticsEventNames} from 'sentry/utils/routeAnalytics/useRouteAnalyticsEventNames';
 import {useRouteAnalyticsParams} from 'sentry/utils/routeAnalytics/useRouteAnalyticsParams';
 import {useApi} from 'sentry/utils/useApi';
@@ -45,7 +45,7 @@ import {RuleListRow} from './row';
 type SortField = 'date_added' | 'name' | ['incident_status', 'date_triggered'];
 const defaultSort: SortField = ['incident_status', 'date_triggered'];
 
-function getAlertListQueryKey(orgSlug: string, query: Location['query']): ApiQueryKey {
+function getAlertListQueryParams(query: Location['query']) {
   const queryParams = {...query};
   queryParams.expand = ['latestIncident', 'lastTriggered'];
   queryParams.team = getTeamParams(queryParams.team!);
@@ -54,12 +54,18 @@ function getAlertListQueryKey(orgSlug: string, query: Location['query']): ApiQue
     queryParams.sort = defaultSort;
   }
 
-  return [
-    getApiUrl('/organizations/$organizationIdOrSlug/combined-rules/', {
+  return queryParams;
+}
+
+function getAlertListApiOptions(orgSlug: string, query: Location['query']) {
+  return apiOptions.as<Array<CombinedAlerts | null>>()(
+    '/organizations/$organizationIdOrSlug/combined-rules/',
+    {
       path: {organizationIdOrSlug: orgSlug},
-    }),
-    {query: queryParams},
-  ];
+      query: getAlertListQueryParams(query),
+      staleTime: 0,
+    }
+  );
 }
 
 const DataConsentBanner = HookOrDefault({
@@ -82,18 +88,12 @@ export default function AlertRulesList() {
   });
 
   // Fetch alert rules
-  const {
-    data: ruleListResponse = [],
-    refetch,
-    getResponseHeader,
-    isPending,
-    isError,
-  } = useApiQuery<Array<CombinedAlerts | null>>(
-    getAlertListQueryKey(organization.slug, location.query),
-    {
-      staleTime: 0,
-    }
-  );
+  const alertListOptions = getAlertListApiOptions(organization.slug, location.query);
+  const {data, refetch, isPending, isError} = useQuery({
+    ...alertListOptions,
+    select: selectJsonWithHeaders,
+  });
+  const ruleListResponse = data?.json ?? [];
 
   const handleChangeFilter = (activeFilters: string[]) => {
     const {cursor: _cursor, page: _page, ...currentQuery} = location.query;
@@ -166,11 +166,15 @@ export default function AlertRulesList() {
 
     try {
       await api.requestPromise(deleteEndpoints[rule.type], {method: 'DELETE'});
-      setApiQueryData<Array<CombinedAlerts | null>>(
-        queryClient,
-        getAlertListQueryKey(organization.slug, location.query),
-        data => data?.filter(r => r?.id !== rule.id && r?.type !== rule.type)
-      );
+      queryClient.setQueryData(alertListOptions.queryKey, previous => {
+        if (!previous) {
+          return previous;
+        }
+        return {
+          ...previous,
+          json: previous.json.filter(r => r?.id !== rule.id && r?.type !== rule.type),
+        };
+      });
       refetch();
       addSuccessMessage(t('Deleted rule'));
     } catch (_err) {
@@ -194,7 +198,7 @@ export default function AlertRulesList() {
           : rule.projects
     )
   );
-  const ruleListPageLinks = getResponseHeader?.('Link');
+  const ruleListPageLinks = data?.headers.Link;
 
   const sort: {asc: boolean; field: SortField} = {
     asc: location.query.asc === '1',

static/app/views/alerts/rules/issue/details/issuesList.tsx

@@ -1,6 +1,7 @@
 import {Fragment} from 'react';
 import {css} from '@emotion/react';
 import styled from '@emotion/styled';
+import {useQuery} from '@tanstack/react-query';
 
 import {Flex} from '@sentry/scraps/layout';
 import {Link} from '@sentry/scraps/link';
@@ -15,10 +16,10 @@ import {t} from 'sentry/locale';
 import type {IssueAlertRule} from 'sentry/types/alerts';
 import type {Group} from 'sentry/types/group';
 import type {Project} from 'sentry/types/project';
-import {getApiUrl} from 'sentry/utils/api/getApiUrl';
+import {apiOptions, selectJsonWithHeaders} from 'sentry/utils/api/apiOptions';
 import {getMessage, getTitle} from 'sentry/utils/events';
 import type {FeedbackIssue} from 'sentry/utils/feedback/types';
-import {useApiQuery} from 'sentry/utils/queryClient';
+import {RequestError} from 'sentry/utils/requestError/requestError';
 import {useOrganization} from 'sentry/utils/useOrganization';
 import {makeFeedbackPathname} from 'sentry/views/feedback/pathnames';
 
@@ -45,25 +46,15 @@ export function AlertRuleIssuesList({
   cursor,
 }: Props) {
   const organization = useOrganization();
-  const {
-    data: groupHistory,
-    getResponseHeader,
-    isPending,
-    isError,
-    error,
-  } = useApiQuery<GroupHistory[]>(
-    [
-      getApiUrl(
-        '/projects/$organizationIdOrSlug/$projectIdOrSlug/rules/$ruleId/group-history/',
-        {
-          path: {
-            organizationIdOrSlug: organization.slug,
-            projectIdOrSlug: project.slug,
-            ruleId: rule.id,
-          },
-        }
-      ),
+  const {data, isPending, error} = useQuery({
+    ...apiOptions.as<GroupHistory[]>()(
+      '/projects/$organizationIdOrSlug/$projectIdOrSlug/rules/$ruleId/group-history/',
       {
+        path: {
+          organizationIdOrSlug: organization.slug,
+          projectIdOrSlug: project.slug,
+          ruleId: rule.id,
+        },
         query: {
           per_page: 10,
           ...(period && {statsPeriod: period}),
@@ -72,15 +63,17 @@ export function AlertRuleIssuesList({
           utc,
           cursor,
         },
-      },
-    ],
-    {staleTime: 0}
-  );
+        staleTime: 0,
+      }
+    ),
+    select: selectJsonWithHeaders,
+  });
+  const groupHistory = data?.json;
 
-  if (isError) {
+  if (error instanceof RequestError) {
     return (
       <LoadingError
-        message={(error?.responseJSON?.detail as string) ?? t('default message')}
+        message={(error.responseJSON?.detail as string) ?? t('default message')}
       />
     );
   }
@@ -140,7 +133,7 @@ export function AlertRuleIssuesList({
         })}
       </StyledPanelTable>
       <Flex justify="end" align="center" marginBottom="xl">
-        <StyledPagination pageLinks={getResponseHeader?.('Link')} size="xs" />
+        <StyledPagination pageLinks={data?.headers.Link} size="xs" />
       </Flex>
     </Fragment>
   );