docs: add api-requests guide #823

Solant · 2025-05-22T16:46:09Z

Background

Some guides on where to place API requests. I added only the English version first to gather feedback.

Copilot

Pull Request Overview

Adds a centralized guide on where and how to organize API request logic and removes inline examples from other docs in favor of linking to the new guide.

Moved detailed “where to store request” examples out of the auth guide into a standalone API-requests guide
Removed an outdated auto-generation types section in the types guide
Introduced api-requests.md with shared and slice-specific patterns, client setup, and generator recommendations

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
i18n/en/docusaurus-plugin-content-docs/current/guides/examples/types.md	Removed “Auto-generation of types” section
i18n/en/docusaurus-plugin-content-docs/current/guides/examples/auth.md	Replaced inline API‐request examples with a reference link
i18n/en/docusaurus-plugin-content-docs/current/guides/examples/api-requests.md	Added new guide covering shared/slice-specific request patterns

Comments suppressed due to low confidence (2)

i18n/en/docusaurus-plugin-content-docs/current/guides/examples/types.md:431

[nitpick] The removal of the auto-generation section removes guidance on handling generated types; consider linking to an external guide or summarizing key steps for regenerating types in a dedicated folder.

## Auto-generation of types

i18n/en/docusaurus-plugin-content-docs/current/guides/examples/api-requests.md:14

[nitpick] Indent this list under 'A typical file structure would be:' by two spaces (e.g. - 📂 shared) to ensure proper nesting and consistent markdown rendering.

- 📂 shared

i18n/en/docusaurus-plugin-content-docs/current/guides/examples/auth.md

i18n/en/docusaurus-plugin-content-docs/current/guides/examples/api-requests.md

illright

I really like how the new page reads, great work! I have some concerns about how the other pages link to this one though — I'd like to see the link more naturally integrated into the narrative

illright · 2025-06-01T09:15:19Z

i18n/en/docusaurus-plugin-content-docs/current/guides/examples/api-requests.md

+
+# Handling API Requests
+
+Feature-Sliced Design provides a structured way to organize your API request logic.


issue: I don't think this statement is very accurate — FSD doesn't provide a way to organize API request logic. I'd say the more accurate description is "here's how to organize request logic with the whole FSD structure"

suggestion: maybe we don't even need this intro and can get straight to the first section?

Agree, abstract intro looks fine in theory, but doesn't add any meaningful information

illright · 2025-06-01T09:18:33Z

i18n/en/docusaurus-plugin-content-docs/current/guides/examples/api-requests.md

+- Default headers (e.g., for authentication).
+- Data serialization.
+
+Here are examples for `axios` and `fetch`:


suggestion (non-blocking): perhaps it would be clearer if we split the axios and fetch examples into different codeblocks? To demonstrate that they are not meant to be used together

illright · 2025-06-01T09:20:47Z

i18n/en/docusaurus-plugin-content-docs/current/guides/examples/api-requests.md

+export interface LoginCredentials {
+  email: string;
+  password: string;
+}


suggestion: I believe it's very common nowadays to pair your backend DTO definitions with runtime data validation with Zod or the likes, perhaps we can add something about it here? Maybe a link to the relevant section of the Types guide will suffice

illright · 2025-06-01T09:23:31Z

i18n/en/docusaurus-plugin-content-docs/current/guides/examples/api-requests.md

praise: great job with this file! It's concise and to the point :)

illright · 2025-06-01T16:19:11Z

i18n/en/docusaurus-plugin-content-docs/current/guides/examples/types.md

@@ -429,10 +429,6 @@ Other packages simply don't have typings, and you might want to declare them as
 declare module "use-react-screenshot";
 ```

-## Auto-generation of types


issue: I don't quite like the idea of removing this section entirely. If I was searching for autogeneration of types, I might look in Types or I might look in API requests.

suggestion: I'd prefer if both pages could pick the user up where they are and show them the way. Perhaps we could also do it in a more elaborate way than just having a link — perhaps we can offer some useful clarifications about the content of that link, i. e. how the content of the link applies to the problem at hand.

So basically I would suggest keeping the heading as is, giving a link to the guide, and also saying something like "if you want to auto-generate types from an OpenAPI schema, put them in shared/api/openapi. If you want to auto-generate types from a Figma icon library, put them in shared/ui.

In fact, maybe we can just paraphrase and not even bother linking, it's just one small paragraph

I rolled this change back to focus on one page at a time, later we can revisit this paragraph if needed

illright · 2025-06-01T16:21:00Z

i18n/en/docusaurus-plugin-content-docs/current/guides/examples/api-requests.md

+
+## Using Client Generators
+
+If your backend has an OpenAPI specification, tools like [orval](https://orval.dev/) or [openapi-typescript](https://openapi-ts.dev/) can generate API types and request functions for you. Place the generated code in `shared/api`.


issue: I suspect some people will also want guidance on where in shared/api to put the generated code. What was nice about the previous version on another page is that it specified a concrete example — shared/api/openapi

suggestion: let's give a specific location here as well, and if they don't like it, they can come up with their own

suggestion: I also like this sentence from the previous version:

Ideally, you should also include a README in that folder that describes what these files are, how to regenerate them, etc.

Could we add that here as well?

illright · 2025-06-01T16:27:46Z

i18n/en/docusaurus-plugin-content-docs/current/guides/examples/auth.md

-```
-
-You don't have to export the `login()` function in the page's public API, because it's unlikely that any other place in the app will need this request.
+Create a function that makes a request to your backend's login endpoint. This function can either be called directly in the component code using a mutation library (e.g. TanStack Query), or it can be called as a side effect in a state manager: [where to store the request function][examples-api-requests].


issue: this link kinda feels patched on top of the text, it doesn't flow naturally, in my opinion.

suggestion: like I wrote in another comment, maybe we could give some clarification about the content of that link, how it's relevant here? Because the linked page is talking about API requests in general, and here we have a very particular API request, so we can offer more precise advice.

I see it as something like "As explained in the [guide for API requests], you can put your request either in shared/api or in the api segment of your login page."

Solant added 6 commits May 22, 2025 18:42

docs: add api-requests guide

0584a4c

docs: improve api-requests documentation

32c7349

docs: add api requests examples

c44be41

docs: move documentation on api requests to the dedicated page

838bfe8

docs: move info about generated clients from types.md to api-requests.md

1d6b202

docs: improve api-requests

46d68e6

illright requested a review from Copilot June 1, 2025 09:13

Copilot AI reviewed Jun 1, 2025

View reviewed changes

i18n/en/docusaurus-plugin-content-docs/current/guides/examples/auth.md Outdated Show resolved Hide resolved

i18n/en/docusaurus-plugin-content-docs/current/guides/examples/api-requests.md Outdated Show resolved Hide resolved

illright requested changes Jun 1, 2025

View reviewed changes

Solant added 2 commits June 11, 2025 00:17

review improvements

8024f60

review improvements

cb85048

Solant marked this pull request as ready for review June 10, 2025 22:24

Solant requested a review from illright June 17, 2025 08:44


		# Handling API Requests

		Feature-Sliced Design provides a structured way to organize your API request logic.


		## Using Client Generators

		If your backend has an OpenAPI specification, tools like [orval](https://orval.dev/) or [openapi-typescript](https://openapi-ts.dev/) can generate API types and request functions for you. Place the generated code in `shared/api`.

docs: add api-requests guide #823

Are you sure you want to change the base?

docs: add api-requests guide #823

Uh oh!

Conversation

Solant commented May 22, 2025

Background

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

illright left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!