RTK Query Endpoints

RTK Query Endpoints

Define query and mutation endpoints with cache tag invalidation, response transformation, and auto-generated hooks

When to Use

• Adding new API endpoints to an existing RTK Query service
• Implementing CRUD operations with automatic cache invalidation
• Transforming API responses before they reach components
• Setting up pagination, polling, or conditional fetching

Instructions

1. Use builder.query for read operations (GET) and builder.mutation for write operations (POST/PUT/DELETE).
2. Provide generic type arguments: builder.query<ReturnType, ArgType>. Use void when there is no argument.
3. Use providesTags on queries to declare what cache entries they populate. Use both list-level and item-level tags.
4. Use invalidatesTags on mutations to declare what cache entries to refetch after the mutation succeeds.
5. Use transformResponse to reshape API responses before caching — extract nested data, normalize structures.
6. Use injectEndpoints from feature modules to keep endpoints co-located with their feature code.
7. Export the auto-generated hooks. Queries produce useXQuery and useLazyXQuery; mutations produce useXMutation.

// features/posts/posts.api.ts
import { api } from '../../services/api';

interface Post {
  id: string;
  title: string;
  body: string;
  authorId: string;
}

const postsApi = api.injectEndpoints({
  endpoints: (builder) => ({
    getPosts: builder.query<Post[], { page: number }>({
      query: ({ page }) => `/posts?page=${page}`,
      providesTags: (result) =>
        result
          ? [
              ...result.map(({ id }) => ({ type: 'Post' as const, id })),
              { type: 'Post', id: 'LIST' },
            ]
          : [{ type: 'Post', id: 'LIST' }],
    }),

    getPost: builder.query<Post, string>({
      query: (id) => `/posts/${id}`,
      providesTags: (result, error, id) => [{ type: 'Post', id }],
    }),

    createPost: builder.mutation<Post, Omit<Post, 'id'>>({
      query: (body) => ({ url: '/posts', method: 'POST', body }),
      invalidatesTags: [{ type: 'Post', id: 'LIST' }],
    }),

    updatePost: builder.mutation<Post, Pick<Post, 'id'> & Partial<Post>>({
      query: ({ id, ...patch }) => ({ url: `/posts/${id}`, method: 'PATCH', body: patch }),
      invalidatesTags: (result, error, { id }) => [{ type: 'Post', id }],
    }),

    deletePost: builder.mutation<void, string>({
      query: (id) => ({ url: `/posts/${id}`, method: 'DELETE' }),
      invalidatesTags: (result, error, id) => [
        { type: 'Post', id },
        { type: 'Post', id: 'LIST' },
      ],
    }),
  }),
});

export const {
  useGetPostsQuery,
  useGetPostQuery,
  useCreatePostMutation,
  useUpdatePostMutation,
  useDeletePostMutation,
} = postsApi;

Details

Tag strategy: Use a 'LIST' sentinel ID for collection queries. Individual item queries use the actual ID. Mutations that add/remove items invalidate 'LIST' to refetch collections. Mutations that edit items invalidate only that item's tag.

transformResponse: Reshape before caching:

getUsers: builder.query<User[], void>({
  query: () => '/users',
  transformResponse: (response: { data: User[]; meta: unknown }) => response.data,
}),

Polling and refetching:

// In component
const { data } = useGetPostsQuery({ page: 1 }, { pollingInterval: 30000 });

// Refetch on window focus — enabled globally via setupListeners(store.dispatch)

Pagination pattern: RTK Query caches each argument combination separately. For page: 1 and page: 2, two cache entries exist. Use serializeQueryArgs + merge + forceRefetch for infinite scroll:

getPosts: builder.query<Post[], number>({
  query: (page) => `/posts?page=${page}`,
  serializeQueryArgs: ({ endpointName }) => endpointName,
  merge: (currentCache, newItems) => { currentCache.push(...newItems); },
  forceRefetch: ({ currentArg, previousArg }) => currentArg !== previousArg,
}),

Source

https://redux-toolkit.js.org/rtk-query/usage/queries

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.