react-query-api-integration

React Query & API Integration Patterns

🎯 MANDATORY: Use React Query for ALL Server State

Sprint 10 revealed that manual useEffect + useState patterns for API calls create unnecessary complexity and bugs. ALWAYS use React Query.

✅ CORRECT PATTERNS:

1. Query Hook Pattern

// ✅ Use useQuery for data fetching
function useCollections() {
  return useQuery({
    queryKey: ['collections'],
    queryFn: async () => {
      const response = await api.get('/api/v1/collections');
      return response.data;
    },
    staleTime: 5 * 60 * 1000, // 5 minutes
    retry: 3,
  });
}

// ✅ Component usage
function CollectionsList() {
  const { data: collections, isLoading, error } = useCollections();
  
  if (isLoading) return <Spinner />;
  if (error) return <ErrorAlert message={error.message} />;
  
  return <CollectionGrid collections={collections} />;
}

2. Mutation Pattern

// ✅ Use useMutation for server modifications
function useCreateCollection() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: async (data: CreateCollectionRequest) => {
      const response = await api.post('/api/v1/collections', data);
      return response.data;
    },
    onSuccess: () => {
      // Invalidate and refetch collections
      queryClient.invalidateQueries({ queryKey: ['collections'] });
      toast.success('Collection created successfully');
    },
    onError: (error) => {
      toast.error(`Failed to create collection: ${error.message}`);
    },
  });
}

3. Background Polling Pattern

// ✅ Job status polling with automatic cleanup
function useJobStatus(jobId: string | null) {
  return useQuery({
    queryKey: ['job-status', jobId],
    queryFn: async () => {
      if (!jobId) throw new Error('No job ID provided');
      const response = await api.get(`/api/v1/ingest/status/${jobId}`);
      return response.data;
    },
    enabled: !!jobId, // Only run when jobId exists
    refetchInterval: (data) => {
      // Stop polling when job is complete
      if (data?.status === 'completed' || data?.status === 'failed') {
        return false;
      }
      return 2000; // Poll every 2 seconds
    },
    retry: false, // Don't retry failed polls
  });
}