createApi

The main point where you will define a service to use in your application.

Parameters

createApi accepts a single configuration object parameter with the following options:

baseQuery(args: InternalQueryArgs, api: QueryApi): any;
endpoints(build: EndpointBuilder<InternalQueryArgs, EntityTypes>): Definitions;
entityTypes?: readonly EntityTypes[];
reducerPath?: ReducerPath;
serializeQueryArgs?: SerializeQueryArgs<InternalQueryArgs>;
keepUnusedDataFor?: number; // value is in seconds
refetchOnMountOrArgChange?: boolean | number; // value is in seconds
refetchOnFocus?: boolean;
refetchOnReconnect?: boolean;

baseQuery

The base query used by each endpoint if no queryFn option is specified. RTK Query exports a utility called fetchBaseQuery as a lightweight wrapper around fetch for common use-cases.

Simulating axios-like interceptors with a custom base query
const baseQuery = fetchBaseQuery({ baseUrl: '/' });
const baseQueryWithReauth: BaseQueryFn<string | FetchArgs, unknown, FetchBaseQueryError> = async (
args,
api,
extraOptions
) => {
let result = await baseQuery(args, api, extraOptions);
if (result.error && result.error.status === '401') {
// try to get a new token
const refreshResult = await baseQuery('/refreshToken', api, extraOptions);
if (refreshResult.data) {
// store the new token
api.dispatch(setToken(refreshResult.data));
// retry the initial query
result = await baseQuery(args, api, extraOptions);
} else {
api.dispatch(loggedOut());
}
}
return result;
};

entityTypes

An array of string entity type names. Specifying entity types is optional, but you should define them so that they can be used for caching and invalidation. When defining an entity type, you will be able to provide them with provides and invalidate them with invalidates when configuring endpoints.

reducerPath

The reducerPath is a unique key that your service will be mounted to in your store. If you call createApi more than once in your application, you will need to provide a unique value each time. Defaults to api.

apis.js
import { createApi, fetchBaseQuery } from '@rtk-incubator/rtk-query';
const apiOne = createApi({
reducerPath: 'apiOne',
baseQuery: fetchBaseQuery('/'),
endpoints: (builder) => ({
// ...endpoints
}),
});
const apiTwo = createApi({
reducerPath: 'apiTwo',
baseQuery: fetchBaseQuery('/'),
endpoints: (builder) => ({
// ...endpoints
}),
});

serializeQueryArgs

summary Defaults to:

export const defaultSerializeQueryArgs: SerializeQueryArgs<any> = ({ endpoint, queryArgs }) => {
// Sort the object keys before stringifying, to prevent useQuery({ a: 1, b: 2 }) having a different cache key than useQuery({ b: 2, a: 1 })
return `${endpoint}(${JSON.stringify(queryArgs, Object.keys(queryArgs || {}).sort())})`;
};

endpoints

Endpoints are just a set of operations that you want to perform against your server. You define them as an object using the builder syntax. There are two basic endpoint types: query and mutation.

Anatomy of an endpoint

  • query (required)

    • query is the only required property, and can be a function that returns either a string or an object which is passed to your baseQuery. If you are using fetchBaseQuery, this can return either a string or an object of properties in FetchArgs. If you use your own custom baseQuery, you can customize this behavior to your liking

  • transformResponse (optional)

    • A function to manipulate the data returned by a query or mutation
    • Unpack a deeply nested collection
      transformResponse: (response) => response.some.nested.collection;
    • Normalize the response data
      transformResponse: (response) =>
      response.reduce((acc, curr) => {
      acc[curr.id] = curr;
      return acc;
      }, {});

  • provides (optional)

    Used by queries to provide entities to the cache Expects an array of entity type strings, or an array of objects of entity types with ids.

    1. ['Post'] - equivalent to b
    2. [{ type: 'Post' }] - equivalent to a
    3. [{ type: 'Post', id: 1 }]

  • invalidates (optional)

    Used by mutations for cache invalidation purposes. Expects the same shapes as provides

  • onStart, onError and onSuccess (optional) - Available to both queries and mutations

    • Can be used in mutations for optimistic updates.
    • Mutation lifecycle signatures
      function onStart(arg: QueryArg, mutationApi: MutationApi<ReducerPath, Context>): void;
      function onError(arg: QueryArg, mutationApi: MutationApi<ReducerPath, Context>, error: unknown): void;
      function onSuccess(arg: QueryArg, mutationApi: MutationApi<ReducerPath, Context>, result: ResultType): void;
    • Query lifecycle signatures
      function onStart(arg: QueryArg, queryApi: QueryApi<ReducerPath, Context>): void;
      function onError(arg: QueryArg, queryApi: QueryApi<ReducerPath, Context>, error: unknown): void;
      function onSuccess(arg: QueryArg, queryApi: QueryApi<ReducerPath, Context>, result: ResultType): void;

How endpoints get used

When defining a key like getPosts as shown below, it's important to know that this name will become exportable from api and be able to referenced under api.endpoints.getPosts.useQuery(), api.endpoints.getPosts.initiate() and api.endpoints.getPosts.select(). The same thing applies to mutations but they reference useMutation instead of useQuery.

const api = createApi({
baseQuery: fetchBaseQuery('/'),
endpoints: (build) => ({
getPosts: build.query<PostsResponse, void>({
query: () => 'posts',
provides: (result) => result.map(({ id }) => ({ type: 'Posts', id })),
}),
addPost: build.mutation<Post, Partial<Post>>({
query: (body) => ({
url: `posts`,
method: 'POST',
body,
}),
invalidates: ['Posts'],
}),
}),
});
// Auto-generated hooks
export { useGetPostsQuery, useAddPostMutation } = api;
// Possible exports
export const { endpoints, reducerPath, reducer, middleware } = api;
// reducerPath, reducer, middleware are only used in store configuration
// endpoints will have:
// endpoints.getPosts.initiate(), endpoints.getPosts.select(), endpoints.getPosts.useQuery()
// endpoints.addPost.initiate(), endpoints.addPost.select(), endpoints.addPost.useMutation()
// see `createApi` overview for _all exports_

Transforming the data returned by an endpoint before caching

In some cases, you may want to manipulate the data returned from a query before you put it in the cache. In this instance, you can take advantage of transformResponse.

By default, the payload from the server is returned directly.

function defaultTransformResponse(baseQueryReturnValue: unknown) {
return baseQueryReturnValue;
}

To change it, provide a function that looks like:

transformResponse: (response) => response.some.deeply.nested.property;
GraphQL transformation example
export const api = createApi({
baseQuery: graphqlBaseQuery({
baseUrl: '/graphql',
}),
endpoints: (builder) => ({
getPosts: builder.query({
query: () => ({
body: gql`
query {
posts {
data {
id
title
}
}
}
`,
}),
transformResponse: (response) => response.posts.data,
}),
}),
});

keepUnusedDataFor

Defaults to 60 (this value is in seconds). This is how long RTK Query will keep your data cached for after the last component unsubscribes. For example, if you query an endpoint, then unmount the component, then mount another component that makes the same request within the given time frame, the most recent value will be served from the cache.

refetchOnMountOrArgChange

Defaults to false. This setting allows you to control whether RTK Query will only serve a cached result, or if it should refetch when set to true or if an adequate amount of time has passed since the last successful query result.

  • false - Will not cause a query to be performed unless it does not exist yet.
  • true - Will always refetch when a new subscriber to a query is added. Behaves the same as calling the refetch callback or passing forceRefetch: true in the action creator.
  • number - Value is in seconds. If a number is provided and there is an existing query in the cache, it will compare the current time vs the last fulfilled timestamp, and only refetch if enough time has elapsed.

If you specify this option alongside skip: true, this will not be evaluated until skip is false.

note

You can set this globally in createApi, but you can also override the default value and have more granular control by passing refetchOnMountOrArgChange to each individual hook call or when dispatching the initiate action.

refetchOnFocus

Defaults to false. This setting allows you to control whether RTK Query will try to refetch all subscribed queries after the application window regains focus.

If you specify this option alongside skip: true, this will not be evaluated until skip is false.

note

You can set this globally in createApi, but you can also override the default value and have more granular control by passing refetchOnFocus to each individual hook call or when dispatching the initiate action.

If you specify track: false when manually dispatching queries, RTK Query will not be able to automatically refetch for you.

refetchOnReconnect

Defaults to false. This setting allows you to control whether RTK Query will try to refetch all subscribed queries after regaining a network connection.

If you specify this option alongside skip: true, this will not be evaluated until skip is false.

note

You can set this globally in createApi, but you can also override the default value and have more granular control by passing refetchOnReconnect to each individual hook call or when dispatching the initiate action.

If you specify track: false when manually dispatching queries, RTK Query will not be able to automatically refetch for you.

Return value

All returned properties
const api = createApi({
baseQuery: fetchBaseQuery('/'),
endpoints: (builder) => ({
// ...
}),
});
export const {
reducerPath,
reducer,
middleware,
endpoints,
internalActions,
util,
injectEndpoints,
enhanceEndpoints,
usePrefetch,
...generatedHooks
} = api;

middleware

This is a standard redux middleware and is responsible for things like polling, garbage collection and a handful of other things. Make sure it's included in your store.

reducer

A standard redux reducer that enables core functionality. Make sure it's included in your store.

endpoints returned by createApi

initiate

React Hooks users will most likely never need to use these in most cases. These are redux action creators that you can dispatch with useDispatch or store.dispatch().

Usage of actions outside of React Hooks

When dispatching an action creator, you're responsible for storing a reference to the promise it returns in the event that you want to update that specific subscription. Also, you have to manually unsubscribe once your component unmounts. To get an idea of what that entails, see the Svelte Example or the React Class Components Example

select

select is how you access your query or mutation data from the cache. If you're using Hooks, you don't have to worry about this in most cases. There are several ways to use them:

React Hooks
const { data, status } = useSelector(api.getPosts.select());
Using connect from react-redux
const mapStateToProps = (state) => ({
data: api.getPosts.select()(state),
});
connect(null, mapStateToProps);
Svelte
$: ({ data, status } = api.getPosts.select()($store));

hooks

Hooks are specifically for React Hooks users. Under each api.endpoint.[endpointName], you will have useQuery or useMutation depending on the type. For example, if you had getPosts and updatePost, these options would be available:

Hooks usage
const { data } = api.endpoints.getPosts.useQuery();
const { data } = api.endpoints.updatePost.useMutation();
const { data } = api.useGetPostsQuery();
const [updatePost] = api.useUpdatePostMutation();

action matchers

These are action matchers for each endpoint to allow you matching on redux actions for that endpoint - for example in slice extraReducers or a custom middleware. Those are implemented as follows:

matchPending: isAllOf(isPending(thunk), matchesEndpoint(endpoint)),
matchFulfilled: isAllOf(isFulfilled(thunk), matchesEndpoint(endpoint)),
matchRejected: isAllOf(isRejected(thunk), matchesEndpoint(endpoint)),

Auto-generated Hooks

React users are able to take advantage of auto-generated hooks. By default, createApi will automatically generate type-safe hooks (TS 4.1+ only) for you based on the name of your endpoints. The general format is use(Endpointname)(Query|Mutation) - use is prefixed, the first letter of your endpoint name is capitalized, then Query or Mutation is appended depending on the type.

Auto-generated hooks example
const api = createApi({
baseQuery,
endpoints: (build) => ({
getPosts: build.query({
query: () => 'posts',
}),
addPost: build.mutation({
query: (body) => ({
url: `posts`,
method: 'POST',
body,
}),
}),
}),
});
// Automatically generated from the endpoint names
export { useGetPostsQuery, useAddPostMutation } = api;

internalActions

danger

These may change at any given time and are not part of the public API for now

  • updateSubscriptionOptions: ActionCreatorWithPayload<{ endpoint: string; requestId: string; options: SubscriptionOptions; queryCacheKey: QueryCacheKey }, string>;
  • queryResultPatched: ActionCreatorWithPayload<{ queryCacheKey: QueryCacheKey, patches: Patch[]; }, string>
  • removeQueryResult: ActionCreatorWithPayload<{ queryCacheKey: QueryCacheKey }, string>
  • unsubscribeQueryResult: ActionCreatorWithPayload<{ queryCacheKey: QueryCacheKey, requestId: string }, string>,
  • unsubscribeMutationResult: ActionCreatorWithPayload<MutationSubstateIdentifier, string>,

util

injectEndpoints

See Code Splitting

enhanceEndpoints

See Code Generation

Edit this page