card-endpoint-shape

Card endpoint shape

Every endpoint is a declaration. Four keys, always in this order:

someEndpoint: build.query<Canonical, Request>({
  query: (request) => ({
    url: "/v1/some/path",
    method: "GET",
  }),
  rawResponseSchema: SomeWireSchema, // the wire shape
  transformResponse: transformSome, // wire -> canonical
  responseSchema: SomeSchema, // what callers receive
});

Key	Answers	Lives in
query	What we send	api.ts
rawResponseSchema	What the backend promised	schema.ts
transformResponse	How it becomes ours	transforms.ts
responseSchema	What the caller gets	schema.ts

Drop the keys you do not need. An endpoint whose wire shape is already canonical declares responseSchema alone — logout and getUser both do.

Return the wire contract, nothing more. A field the backend never sent does not belong on the answer. If a caller needs one of its own request values afterwards, it already has it.

Never use queryFn

queryFn is the escape hatch for endpoints that are not one HTTP call. None here is, and it costs more than it looks:

• RTK Query skips transformResponse for a queryFn endpoint. getTransformCallbackForEndpoint in buildThunks is guarded by endpointDefinition.query &&. The mapper is silently ignored, so the mapping moves inside the function, by hand.
• The baseQuery result is unknown, so the body needs a cast or a manual safeParse.
• Every one brings its own if (response.error) return { error: response.error }.

Three lines of declaration become twenty of plumbing, and the endpoint stops reading like its neighbours.

An endpoint that handles a credential

The two OAuth2 grants are endpoints like any other, plus three rules. RTK Query puts the argument of a call on its pending action and the answer on its settled one, so a grant's credential travels through redux, and three controls keep it out of every reader:

• extraOptions: { authenticated: false }, so the base query sends no Bearer and never renews. A grant presents its own credential, and a grant that renewed would loop on its own 401.
• No hook. Export a hook for every other endpoint, and none for a grant.
• track: false at every call site, so the answer never becomes a cache entry in redux state.