RTK Query: Please advise on how to scale the api

[azangru]

1. General concern

What I am painfully missing in RTK-query documentation is an advice on how to grow rtk-query slices in a medium to large-scale application. Specifically:

• What's the best way of thinking about "apis" that are created with the createApi function?
  • How many apis is it normal for an application to have?
  • Are api slices resulting from createApi expected to be mentally mapped to the backends that the client queries? For example, if there are three different backend microservices that the client talks to, would one expect to have three rtk-query api slices?
  • How would one normally handle scenarios when data is collected from several backend apis at once, by querying them either in parallel or sequentially? Is this what action-listener-middleware is intended for, or is this a problem that rtk-query solves on its own? UPDATED: found an answer to this question in the docs.
• What's the proper way of splitting the logic of an api slice into multiple files?
  • If it is through the injectEndpoints method, then is there any way to avoid naming collisions, other than following some internal naming conventions within the development team?
• Do you have an example of a codebase following these practices that you could reference?

2. Example: specific pain point

Here is a simplified scenario based on an application I am working on. Suppose we have an app that combines multiple instruments for exploring genes. The app is split into several large parts; let's call them genome viewer, gene viewer, and sequence viewer. Each part has multiple screens.

The app uses multiple backend apis; but let's consider just one, which is a graphql api.

So, suppose, we structure the app like this:

First, create a rtk-query api for talking to the graphql backend

const myGraphqlApi = createApi({
  reducerPath: 'myGraphqlApi',
  baseQuery: graphqlBaseQuery({
    baseUrl: '/api/my-graphql'
  }),
  endpoints: () => ({}) // will inject endpoints in other files
});


export default myGraphqlApi;

Then, use this newly created myGraphqlApi in a slice responsible for queries for the genome viewer

import myGraphqlApi from 'src/my-graphql-api';

import { geneSummaryQuery } from 'src/genome-view/queries';

import type { GeneSummaryQueryResult, GeneQueryParams } from 'src/genome-view/types';

const genomeViewerApiSlice = myGraphqlApi.injectEndpoints({
  endpoints: (builder) => ({
    geneSummary: builder.query<GeneSummaryQueryResult, GeneQueryParams>(
      {
        query: (params) => ({
          body: geneSummaryQuery,
          variables: params
        })
      }
    )
  })

As well as, in a different slice, responsible for queries for the gene viewer

import myGraphqlApi from 'src/my-graphql-api';

import { geneSummaryQuery } from 'src/gene-view/queries';

import type { GeneSummaryQueryResult, GeneQueryParams } from 'src/gene-view/types';

const genomeViewerApiSlice = myGraphqlApi.injectEndpoints({
  endpoints: (builder) => ({
    geneSummary: builder.query<GeneSummaryQueryResult, GeneQueryParams>(
      {
        query: (params) => ({
          body: geneSummaryQuery,
          variables: params
        })
      }
    )
  })

Uh-oh! We have a problem. There is a name collision between injected endpoints — both are called geneSummary. But it's completely natural to expect that in the genome-view part of my app I can request a gene summary that will have one set of fields, whereas in the gene-view part of my app I can request a gene summary with an entirely different set of fields. Both of them are gene summaries, but they exist within different contexts. Does this mean that I should have created a "genome view api" and a "gene view api" instead of a "my graphql api"? What if each of the views also talks to different backends — would I end up with a "genome view graphql api", "genome view rest api", "gene view graphql api", and "gene view rest api", and so on?

I hope you can appreciate my confusion. Please, could you kindly advise?

[markerikson]

Some high-level summary answers:

• We recommend that an app should only have one API slice by default: https://redux-toolkit.js.org/rtk-query/api/createApi . Per that note:
  • "Multiple separate base URLs" is roughly the minimum bar to consider defining a second entire API slice, but you can talk to multiple servers in one API slice just by specifying the full URL for an endpoint
  • you can split the endpoint definitions across multiple files with apiSlice.injectEndpoints() and it's still "one API slice"
• Multiple requests in parallel would normally be done by running all the hooks inside the same component, causing all the initial requests to kick off at the same time. Running requests in serial is usually done with conditional fetching, and tracking some state to decide "first request is done, now we can start the next".
• Naming collisions is frankly not a thing that's come up yet during the RTKQ dev process or the questions so far, so we don't have specific suggestions here, and no specific larger app example around this beyond the basic "here's how to inject endpoints" docs examples
• Per https://redux-toolkit.js.org/rtk-query/usage/code-splitting , I believe you should get an error in development if there is a name clash when you inject the duplicate endpoint

[azangru]

Per https://redux-toolkit.js.org/rtk-query/usage/code-splitting , I believe you should get an error in development if there is a name clash when you inject the duplicate endpoint

What prompted me to start this discussion was a bug that I experienced in development and that puzzled me for about half an hour, because it affected a part of the codebase that I wasn't even touching, until I realised that I was using the same endpoint name in two different files that were injecting endpoints into the api slice, and that one injected endpoint overwrote the other. I have just checked again — and can confirm that there were no errors about that in the dev tools.

I'm extremely torn about this. I understand why this is happening; but at the same time, naming is hard, veryLongDescriptiveUniqueNamesAreUgly, and it was a very nasty surprise to discover that RTK-query's philosophy is to have a unique name per endpoint across not just a single file, but an entire app, no matter how large it grows. I can't imagine I will be the only one complaining.

[markerikson]

Honestly, there's only so many use cases we can think of during initial development :)

The RTKQ API is 95% "stuff that Lenz thought of", and a few additional suggestions from folks who tried it out. Lenz is amazing, but only one person and can't think of everything :)

Any hypothetical suggestions for possible ways to address this use case better?

Also, was the other endpoint setting overrideExisting in injectEndpoints()? Because otherwise I would expect an error to be thrown otherwise, and if not that's a bug.

[phryneas]

Yes, unless you enable overrideExisting you should totally get an error message on this.
overrideExisting is a guard against accidentally using the same endpoint name twice - actually I did think about this very problem 😅