📡 RTK Query Basics

What is RTK Query?

RTK Query is a data-fetching and caching solution built into Redux Toolkit. It is purpose-built for server state: data that lives on a server, that you fetch, cache, and keep fresh. It generates the thunks, the reducer, the cache, and the React hooks — so you stop hand-writing that machinery entirely.

Under the hood it's still Redux Toolkit — createAsyncThunk and a slice you never have to write. You get a thin declarative layer on top.

Before & After

Compare the amount of code needed to fetch and display one user. The manual version is everything you built last lesson; the RTK Query version is a few lines.

Before — manual thunk + reducer + component

// thunk
export const fetchUser = (id) => async (dispatch) => {
  dispatch({ type: 'FETCH_USER_REQUEST' });
  try {
    const res = await api.get(`/users/${id}`);
    dispatch({ type: 'FETCH_USER_SUCCESS', payload: res.data });
  } catch (err) {
    dispatch({ type: 'FETCH_USER_FAILURE', payload: err.message });
  }
};

// reducer (omitted — the usual switch with loading/error/user)

// component
const UserProfile = ({ userId }) => {
  const dispatch = useDispatch();
  const { user, loading, error } = useSelector((s) => s.user);
  useEffect(() => { dispatch(fetchUser(userId)); }, [dispatch, userId]);
  if (loading) return <div>Loading...</div>;
  if (error)   return <div>Error: {error}</div>;
  return <div>{user.name}</div>;
};

After — one endpoint, one hook

// services/api.js
import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react';

export const api = createApi({
  baseQuery: fetchBaseQuery({ baseUrl: '/api' }),
  endpoints: (builder) => ({
    getUser: builder.query({ query: (id) => `users/${id}` })
  })
});

export const { useGetUserQuery } = api;   // hook generated automatically

// component
const UserProfile = ({ userId }) => {
  const { data: user, isLoading, error } = useGetUserQuery(userId);
  if (isLoading) return <div>Loading...</div>;
  if (error)     return <div>Error loading user</div>;
  return <div>{user.name}</div>;
};

Creating an API Slice

You define one API slice per base URL with createApi. It takes a reducerPath (where its cache lives in the store), a baseQuery (how requests are made), and an endpoints builder describing each operation.

import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react';

export const apiSlice = createApi({
  reducerPath: 'api',                                    // state.api holds the cache
  baseQuery: fetchBaseQuery({ baseUrl: '/api' }),        // a thin fetch wrapper
  tagTypes: ['Post'],                                    // cache tag names (see below)
  endpoints: (builder) => ({
    // QUERY endpoints — read data
    getPosts: builder.query({
      query: () => '/posts'
    }),
    getPost: builder.query({
      query: (postId) => `/posts/${postId}`
    }),

    // MUTATION endpoints — write data
    addNewPost: builder.mutation({
      query: (initialPost) => ({
        url: '/posts',
        method: 'POST',
        body: initialPost
      })
    }),
    updatePost: builder.mutation({
      query: ({ id, ...patch }) => ({
        url: `/posts/${id}`,
        method: 'PATCH',
        body: patch
      })
    })
  })
});

// Hooks are generated from endpoint names: use + Name + Query/Mutation
export const {
  useGetPostsQuery,
  useGetPostQuery,
  useAddNewPostMutation,
  useUpdatePostMutation
} = apiSlice;

Store Setup

The API slice generates both a reducer and a middleware. Add the reducer under its reducerPath, and concat the middleware onto the defaults — the middleware is what powers caching, invalidation, and polling.

import { configureStore } from '@reduxjs/toolkit';
import { apiSlice } from './features/api/apiSlice';

export const store = configureStore({
  reducer: {
    [apiSlice.reducerPath]: apiSlice.reducer,   // → state.api
    // ...your other slice reducers
  },
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().concat(apiSlice.middleware)
});

Query Endpoints & Hooks

Each query endpoint generates a hook. Call it in a component and it returns the data plus a rich set of status flags. The hook automatically starts the fetch on mount and subscribes the component to that cache entry.

Basic query

const PostsList = () => {
  const { data: posts, isLoading, isError, error } = useGetPostsQuery();

  if (isLoading) return <div>Loading...</div>;
  if (isError)   return <div>Error: {error.status}</div>;

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
};

Query with an argument

Whatever you pass to the hook becomes the argument to the endpoint's query function — and part of the cache key, so each id is cached separately.

const SinglePost = ({ postId }) => {
  const { data: post, isLoading } = useGetPostQuery(postId);
  if (isLoading) return <div>Loading...</div>;
  return (
    <article>
      <h2>{post.title}</h2>
      <p>{post.content}</p>
    </article>
  );
};

Conditional fetching with skip

const UserPosts = ({ userId }) => {
  // Don't fire the query until we actually have a userId
  const { data: posts } = useGetPostsQuery(userId, { skip: !userId });
  return posts ? <PostsList posts={posts} /> : null;
};

Mutation Endpoints

Mutations change server data (POST/PATCH/DELETE). Their hook returns a tuple: a trigger function you call to fire the request, and a result object with status flags.

const AddPostForm = () => {
  const [addNewPost, { isLoading }] = useAddNewPostMutation();
  const [title, setTitle] = useState('');
  const [content, setContent] = useState('');

  const handleSubmit = async (e) => {
    e.preventDefault();
    try {
      // .unwrap() throws on failure so try/catch works
      await addNewPost({ title, content }).unwrap();
      setTitle('');
      setContent('');
    } catch (err) {
      console.error('Failed to save the post:', err);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input value={title} onChange={(e) => setTitle(e.target.value)} placeholder="Title" />
      <textarea value={content} onChange={(e) => setContent(e.target.value)} placeholder="Content" />
      <button type="submit" disabled={isLoading}>
        {isLoading ? 'Saving...' : 'Save Post'}
      </button>
    </form>
  );
};

const [trigger, result] = useAddNewPostMutation();
// trigger(arg)         → fires the request, returns a promise (.unwrap() available)
// result.isLoading     → request in flight
// result.isSuccess     → completed OK
// result.error         → set on failure

The Cache & Tags

Here's the feature that makes RTK Query feel magical: after you add a post, the list of posts updates on its own — no manual dispatch, no refetch call. That's cache invalidation via tags.

The idea is a publish/subscribe contract between queries and mutations:

• A query provides tags — "this cached data is tagged Post."
• A mutation invalidates tags — "I changed Post data; anything tagged Post is now stale."
• RTK Query automatically re-fetches every mounted query whose tags were invalidated.

const apiSlice = createApi({
  reducerPath: 'api',
  baseQuery: fetchBaseQuery({ baseUrl: '/api' }),
  tagTypes: ['Post'],
  endpoints: (builder) => ({
    getPosts: builder.query({
      query: () => '/posts',
      // Tag the list, and each post by id
      providesTags: (result) =>
        result
          ? [...result.map(({ id }) => ({ type: 'Post', id })), { type: 'Post', id: 'LIST' }]
          : [{ type: 'Post', id: 'LIST' }]
    }),
    getPost: builder.query({
      query: (id) => `/posts/${id}`,
      providesTags: (result, error, id) => [{ type: 'Post', id }]
    }),
    addNewPost: builder.mutation({
      query: (body) => ({ url: '/posts', method: 'POST', body }),
      // New post → the LIST is stale → getPosts re-fetches automatically
      invalidatesTags: [{ type: 'Post', id: 'LIST' }]
    }),
    updatePost: builder.mutation({
      query: ({ id, ...patch }) => ({ url: `/posts/${id}`, method: 'PATCH', body: patch }),
      // Editing post 5 → invalidate exactly that post's cached data
      invalidatesTags: (result, error, { id }) => [{ type: 'Post', id }]
    })
  })
});

Practice & Quiz

import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react';

export const todoApi = createApi({
  reducerPath: 'todoApi',
  baseQuery: fetchBaseQuery({ baseUrl: '/api' }),
  tagTypes: ['Todo'],
  endpoints: (builder) => ({
    // TODO: getTodos query (provides Todo/LIST)
    // TODO: addTodo mutation (invalidates Todo/LIST)
  })
});

// TODO: export the generated hooks

endpoints: (builder) => ({
  getTodos: builder.query({
    query: () => '/todos',
    providesTags: [{ type: 'Todo', id: 'LIST' }]
  }),
  addTodo: builder.mutation({
    query: (todo) => ({ url: '/todos', method: 'POST', body: todo }),
    invalidatesTags: [{ type: 'Todo', id: 'LIST' }]
  })
})

export const { useGetTodosQuery, useAddTodoMutation } = todoApi;

const { data: posts, isLoading } = useGetPostsQuery();
if (isLoading) return <Spinner />;   // fires on every background re-fetch too

const { data: posts, isLoading, isFetching } = useGetPostsQuery();
if (isLoading) return <Spinner />;   // first load only
return (
  <div>
    {isFetching && <small>Refreshing...</small>}
    <PostsList posts={posts} />
  </div>
);

Best Practices & Pitfalls

✅ Do

• Define one API slice per base URL and add all endpoints to it
• Always .concat(apiSlice.middleware) in configureStore
• Use providesTags / invalidatesTags so the UI stays in sync automatically
• Use isLoading for first load, isFetching for background refreshes
• Let RTK Query own server state; keep Redux slices for genuine client state (UI, auth)

❌ Don't

• Fetch RTK Query data inside useEffect — the hook already does that
• Copy query results into a separate slice — read them from the cache via the hook
• Manually track loading/error state — the hook exposes it
• Create a new createApi per component — endpoints belong on the shared slice

getPosts: builder.query({
  query: () => '/posts',
  transformResponse: (response) =>
    [...response].sort((a, b) => new Date(b.date) - new Date(a.date))
})

Summary

📚 Additional Resources

• RTK Query — Overview
• RTK Query — Queries
• RTK Query — Mutations
• RTK Query — Automated Re-fetching with Tags

🚀 What's Next?

RTK Query caches server data flat by endpoint, but complex apps also need to manage relational client state efficiently. Next up: Normalized state structure — organizing collections as id-keyed lookups so updates stay fast and duplication-free.