API ベストプラクティス

最終更新: 2026-05-01 API Reference: /docs/api-reference — Scalar UI で OpenAPI 3.2 を検索 API 仕様: /docs/api-reference

技術メモ: Critical Anti-Patterns

技術メモ: Anti-Pattern 1: N+1 Queries in List Views

// ❌ WRONG: 50 items = 50 API calls!
documents.forEach((doc) => fetchLinkedDocuments(doc.id))

// ✅ CORRECT: Single batch call
const documentIds = documents.map((d) => d.id)
const { data: counts } = useDocumentLinkedCounts(documentIds)

技術メモ: Anti-Pattern 2: Unconditional Fetching

// ❌ WRONG: Always fetches, even if panel is closed
const { data } = useDocumentLinkedDocuments(documentId)
const [isPanelOpen, setIsPanelOpen] = useState(false)

// ✅ CORRECT: Only fetch when needed
const { data } = useDocumentLinkedDocuments(documentId, {
  enabled: isPanelOpen,
})

技術メモ: Anti-Pattern 3: Separate Calls for /full Data

// ❌ WRONG: Data is already in /full response
const { data: doc } = useGetDocumentByIdQuery({ documentId })
const { data: attachments } = useGetDocumentAttachmentsQuery({ documentId })
const { data: expenses } = useGetDocumentExpensesQuery({ documentId })

// ✅ CORRECT: Single /full call
const { data } = useDocumentFull({
  documentId,
  includeAttachments: true,
  includeExpenses: true,
})

技術メモ: Anti-Pattern 4: Direct API Calls in useEffect

// ❌ WRONG: Bypasses cache
useEffect(() => {
  const fetchData = async () => {
    const response = await apiClient.get(`/documents/${id}`)
    setData(response.data)
  }
  fetchData()
}, [id])

// ✅ CORRECT: Use TanStack Query
const { data } = useDocumentFull({ documentId: id })

技術メモ: Query Configuration

技術メモ: Required Options for All Queries

return useQuery({
  queryKey: [QUERY_KEYS.FEATURE.ACTION, params],
  queryFn: () => api.fetchData(params),
  enabled: !!requiredParam, // REQUIRED
  staleTime: 60_000, // REQUIRED (30s minimum)
  gcTime: 5 * 60_000, // RECOMMENDED
  refetchOnWindowFocus: false, // REQUIRED
  refetchOnMount: false, // RECOMMENDED
})

技術メモ: Recommended staleTime by Data Type

Data Type	staleTime	Reason
Static/Config	10-30 min	Rarely changes
Reference Data	5-10 min	Changes infrequently
List Data	1-2 min	Changes with operations
Individual Items	30-60 sec	May be edited
Real-time	15-30 sec	Notifications, stats
AI/Expensive	5 min	Avoid re-running

技術メモ: The /full Endpoint

The backend provides a consolidated endpoint that returns all document-related data in a single request.

技術メモ: Endpoint

GET /api/documents/:id/full?include_linked_docs=true&include_attachments=true&include_expenses=true&include_dock=true

技術メモ: Performance Comparison

Pattern	API Calls	Latency
Before (separate calls)	5-6 calls	~2700ms
After (/full endpoint)	1 call	~180ms
Improvement	-83%	-93%

技術メモ: Response Structure

{
  document: {
    document: { /* actual document */ },
    documentVersions: { /* version info */ }
  },
  linkedDocs: { linkedDocuments: [] },
  attachments: [],
  expenses: [],
  dockData: {
    currentDocument: { id, workflowStage, progress },
    claimsDocuments: [{ id, totalAmount, attachmentCount }],
    totalReimbursementAmount: number
  },
  meta: { includedFields: [], fetchTimeMs: number }
}

技術メモ: Usage

import { useDocumentFull } from "@/features/document/hooks/use-document-full"

const { data, isLoading } = useDocumentFull({
  documentId,
  includeLinkedDocs: true,
  includeAttachments: true,
  includeExpenses: true,
  includeDock: true,
  enabled: !!documentId,
})

// Access data
const document = data?.document?.document
const expenses = data?.expenses
const dockData = data?.dockData

技術メモ: Cache Pre-Population

The hook automatically pre-populates caches:

// After /full, these caches are populated:
;["getDocumentById", documentId][("getDocumentExpenses", documentId)][
  ("getDocumentAttachments", documentId)
]

// Other components using individual hooks get cached data!
const { data } = useGetDocumentExpensesQuery({ documentId }) // NO new call!

技術メモ: List vs Detail Patterns

技術メモ: List View Pattern

Use batch APIs - never fetch individual details per item.

function DocumentList() {
  const { data: documents } = useDocumentListQuery({ page: 1, limit: 50 })
  const documentIds = documents?.items?.map(d => d.id) || []

  // Single batch call for all linked counts
  const { data: linkedCounts } = useDocumentLinkedCounts(documentIds)

  return (
    <table>
      {documents?.items?.map(doc => (
        <tr key={doc.id}>
          <td>{doc.name}</td>
          <td>{linkedCounts?.data?.[doc.id]?.count || 0}</td>
        </tr>
      ))}
    </table>
  )
}

技術メモ: Detail View Pattern

Fetch full details only when viewing, use enabled for panels.

function DocumentDetail({ documentId }) {
  const [isLinkPanelOpen, setIsLinkPanelOpen] = useState(false)

  // Always fetch - user is viewing
  const { data: document } = useDocumentDetailQuery(documentId)

  // Only fetch when panel opens
  const { data: linkedDocs } = useDocumentLinkedDocuments(documentId, {
    enabled: isLinkPanelOpen
  })

  return (
    <div>
      <DocumentViewer data={document} />
      <button onClick={() => setIsLinkPanelOpen(true)}>View Links</button>
      {isLinkPanelOpen && <LinkPanel data={linkedDocs} />}
    </div>
  )
}

技術メモ: Batch API Usage

技術メモ: Available Batch Endpoints

Endpoint	Purpose
`GET /documents/linked-counts?ids=a,b,c`	Linked counts for multiple docs
`POST /transactions/batch-analyze`	AI analysis for multiple transactions
`GET /clients?ids=a,b,c`	Multiple clients by ID

技術メモ: Batch Hook Pattern

export const useDocumentLinkedCounts = (documentIds: string[]) => {
  // Deduplicate and sort for consistent cache key
  const uniqueSortedIds = [...new Set(documentIds)].sort()

  return useQuery({
    queryKey: ["document-links", "counts", uniqueSortedIds],
    queryFn: () => documentLinksApi.getLinkedCounts(uniqueSortedIds),
    enabled: uniqueSortedIds.length > 0,
    staleTime: 60_000,
    refetchOnWindowFocus: false,
    refetchOnMount: false,
  })
}

技術メモ: When to Request New Batch Endpoints

If you need to:

Call same API for multiple items in a loop
Display aggregate data in a list view
Pre-fetch for multiple items

Ask Backend Team to create a batch endpoint.

技術メモ: Query Key Best Practices

技術メモ: Hierarchical Structure

// ✅ Good: Clear hierarchy
;["documents", "list", { status: "active", page: 1 }][
  ("documents", "detail", documentId)
][("documents", "detail", documentId, "attachments")][
  // ❌ Bad: Inconsistent
  ("getDocuments", params)
][("document-attachments", documentId)]

技術メモ: Factory Functions

export const DOCUMENT_QUERY_KEYS = {
  all: ["documents"] as const,
  lists: () => [...DOCUMENT_QUERY_KEYS.all, "list"] as const,
  list: (params) => [...DOCUMENT_QUERY_KEYS.lists(), params] as const,
  details: () => [...DOCUMENT_QUERY_KEYS.all, "detail"] as const,
  detail: (id) => [...DOCUMENT_QUERY_KEYS.details(), id] as const,
  attachments: (id) =>
    [...DOCUMENT_QUERY_KEYS.detail(id), "attachments"] as const,
}

// Usage
useQuery({ queryKey: DOCUMENT_QUERY_KEYS.detail(documentId) })

// Invalidation
queryClient.invalidateQueries({
  queryKey: DOCUMENT_QUERY_KEYS.detail(documentId),
})

技術メモ: Normalize Parameters

// ❌ Bad: Different key order = cache miss
useQuery({ queryKey: ["docs", { status: "active", page: 1 }] })
useQuery({ queryKey: ["docs", { page: 1, status: "active" }] }) // Different!

// ✅ Good: Sort parameters
const normalizedParams = Object.keys(params)
  .sort()
  .reduce((acc, key) => ({ ...acc, [key]: params[key] }), {})

技術メモ: Audit Checklist

Before submitting PR with API calls:

技術メモ: Query Configuration

enabled used for conditional fetching
staleTime set (minimum 30s)
refetchOnWindowFocus: false
refetchOnMount: false where appropriate

技術メモ: List Views

NOT calling individual APIs per item
Using batch APIs for aggregate data
Passing deduplicated/sorted IDs

技術メモ: Detail Views

Panel data only fetched when opened
Using appropriate query keys

技術メモ: Performance

Checked Network tab for duplicates
No loops calling APIs
Batch endpoints used where available

技術メモ: Quick Reference

Scenario	Solution
Need counts for 50 items	Batch API: `GET /documents/linked-counts?ids=...`
Panel with document details	`enabled: isPanelOpen`
Same data needed by multiple components	Same query key, let TanStack Query dedupe
User might never need this data	`enabled: false` until needed
Data changes rarely	`staleTime: 10 * 60 * 1000`
Data changes often	`staleTime: 30 * 1000`
AI/expensive operation	`staleTime: 5 * 60 * 1000`

技術メモ: Key Files

File	Purpose
`src/features/document/hooks/use-document-full.ts`	Consolidated fetch hook
`src/features/document/components/hydrate-document-data.tsx`	Document viewer data layer
`src/lib/query-config.ts`	TanStack Query cache config

API ベストプラクティス

目次

技術メモ: Critical Anti-Patterns

技術メモ: Anti-Pattern 1: N+1 Queries in List Views

技術メモ: Anti-Pattern 2: Unconditional Fetching

技術メモ: Anti-Pattern 3: Separate Calls for /full Data

技術メモ: Anti-Pattern 4: Direct API Calls in useEffect

技術メモ: Query Configuration

技術メモ: Required Options for All Queries

技術メモ: Recommended staleTime by Data Type

技術メモ: The /full Endpoint

技術メモ: Endpoint

技術メモ: Performance Comparison

技術メモ: Response Structure

技術メモ: Usage

技術メモ: Cache Pre-Population

技術メモ: List vs Detail Patterns

技術メモ: List View Pattern

技術メモ: Detail View Pattern

技術メモ: Batch API Usage

技術メモ: Available Batch Endpoints

技術メモ: Batch Hook Pattern

技術メモ: When to Request New Batch Endpoints

技術メモ: Query Key Best Practices

技術メモ: Hierarchical Structure

技術メモ: Factory Functions

技術メモ: Normalize Parameters

技術メモ: Audit Checklist

技術メモ: Query Configuration

技術メモ: List Views

技術メモ: Detail Views

技術メモ: Performance

技術メモ: Quick Reference

技術メモ: Key Files

関連ドキュメント