Data Fetching & API Clients
Scope
This section covers libraries, techniques, and patterns for fetching data from APIs (REST, GraphQL, etc.), managing server state synchronization (caching, background updates, mutations), handling API request states (loading, error, success), and specific API paradigms we interact with.
Overview
ADOPT
Proven technologies we have high confidence in; our default choices.
Technologies Breakdown
Fetch API ADOPT
The browser's built-in standard for making HTTP requests. Use for simple, one-off requests where the overhead of a dedicated library or server state management isn't necessary (e.g., simple API calls in utility scripts, basic form submissions). Also serves as the foundation for many higher-level libraries.
Native browser API, requires no external dependencies. Universally available. Sufficient for basic needs, but lacks features like interceptors, automatic transforms, or advanced cancellation found in libraries like Axios or the caching/sync features of React Query/SWR. Adopted as the fundamental baseline.
Axios ADOPT
Recommended HTTP client library when more features than Fetch API are needed, but a full server state management library (like React Query) is not being used or is inappropriate for the specific task. Useful for its interceptors, request/response transformation, and cancellation tokens.
Provides a more convenient and feature-rich API over the native Fetch API (e.g., automatic JSON parsing, interceptors for auth/logging, easier error handling). Widely used and understood. Adopted as the preferred general-purpose HTTP client when advanced features beyond Fetch are required.
React Query (TanStack Query) ADOPT
The standard and strongly recommended library for managing server state (fetching, caching, synchronizing, updating) in React/Next.js applications. Use for virtually all data fetching that populates UI components.
Dramatically simplifies server state management, handling caching, background updates, stale-while-revalidate, mutations, pagination, infinite queries, and more out-of-the-box. Improves performance and user experience significantly. Reduces boilerplate compared to manual state management for fetched data. Strong community, excellent documentation, and actively maintained. Adopted as the default choice for server state.
RESTful APIs ADOPT
The standard and strongly recommended library for managing server state (fetching, caching, synchronizing, updating) in React/Next.js applications. Use for virtually all data fetching that populates UI components.
GraphQL (Paradigm & Clients) TRIAL
Explore on specific projects where its benefits (requesting specific data, avoiding over/under-fetching, strong typing) seem particularly advantageous compared to traditional REST APIs. Use appropriate client libraries like Apollo Client (for feature-rich caching) or urql (for lighter needs) during the trial.
GraphQL offers a powerful alternative to REST for API communication, potentially improving efficiency and developer experience. We are actively trialing it on selected projects to gain deeper experience, evaluate its impact on frontend/backend collaboration, understand the complexities of its ecosystem (client libraries, schema stitching, etc.), and determine if its benefits warrant broader adoption for specific types of applications.
tRPC ASSESS
Explore on full-stack TypeScript projects (especially those using Next.js or Node.js backends) where end-to-end type safety between backend and frontend is highly desirable. Evaluate its developer experience, impact on build process, and suitability for team workflow.
Offers automatic end-to-end type safety without code generation, simplifying API integration and reducing runtime errors in full-stack TypeScript applications. Promises significant DX improvements. Trialing to assess its practical benefits, learning curve, potential limitations, and overall fit for our full-stack development practices compared to traditional REST/GraphQL approaches.
SWR ASSESS
Monitor as a prominent alternative to React Query, particularly noting its development by Vercel and potential optimizations within the Next.js ecosystem. Investigate its specific features (e.g., default revalidation behaviour, hook API) and compare its performance and DX against React Query in specific scenarios via PoCs if warranted.
A popular and capable server state library similar to React Query. Given our adoption of React Query, SWR is placed in Assess. We need to understand if it offers compelling advantages in specific situations or aligns better with potential future framework choices (e.g., deeper Next.js integration) before considering it for Trial or Adopt.
GraphQL ASSESS
We are assessing GraphQL as a potential alternative to REST, particularly for APIs serving complex front-end or mobile applications. Its ability to provide clients with flexible and efficient data-fetching capabilities warrants formal exploration with a proof-of-concept.
gRPC HOLD
The use of gRPC is restricted to projects with specific client requirements that mandate its high-performance, contract-based communication protocol. We are putting it on hold for general development to favor the simplicity and broader interoperability of our standard REST APIs.