docs: Refactor documentation structure and add new guides by patrikbraborec · Pull Request #824 · apify/apify-client-js

patrikbraborec · 2026-01-16T11:02:04Z

Summary

Reorganized documentation into a clearer three-tier structure (introduction, concepts, guides)
Added comprehensive new documentation for authentication, client architecture, error handling, and dataset retrieval
Updated sidebar navigation to reflect the new structure

Test plan

Review the new documentation structure
Verify all internal links work correctly
Check that the sidebar navigation is logical and easy to follow
Ensure code examples are accurate and complete

🤖 Generated with Claude Code

Reorganized documentation into a clearer three-tier structure: - 01_introduction: Overview, installation, and quick start - 02_concepts: Core concepts like authentication, client architecture, error handling, retries, pagination, and nested clients - 03_guides: Practical guides for common use cases Added comprehensive new documentation: - Authentication guide with API token management - Client architecture explanation - Error handling and retry strategies - Dataset retrieval guide Updated sidebar navigation to reflect the new structure. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

janbuchar

I like the direction this is going!

janbuchar · 2026-02-03T13:57:22Z

docs/01_introduction/installation.md

+
+## Authentication and Initialization
+
+To use the client, you need an [API token](https://docs.apify.com/platform/integrations/api#api-token). You can find your token under [Integrations](https://console.apify.com/account/integrations) tab in Apify Console. Copy the token and initialize the client by providing the token (`MY-APIFY-TOKEN`) as a parameter to the `ApifyClient` constructor.


Does this use copy from the original guide or is it generated anew? I think it could use some proofreading - I'd expect a "the" before "Integrations tab", and I've seen several other grammar issues in this doc.

janbuchar · 2026-02-03T13:58:48Z

docs/01_introduction/installation.md

+
+:::note Resource identification
+
+The resource ID can be either the `id` of the said resource, or a combination of your `username/resource-name`.


I believe this only applies to Actors?

janbuchar · 2026-02-03T13:59:37Z

docs/01_introduction/installation.md

+const myActor = await actorClient.get();
+// Starts the run of john-doe/my-actor and returns the Run object.
+const myActorRun = await actorClient.start();
+```


Maybe link to client architecture concepts page from here for a more detailed description?

janbuchar · 2026-02-03T14:54:07Z

docs/01_introduction/quick-start.md

+description: 'Get started with the Apify client for JavaScript by running your first Actor and retrieving results.'
+---
+
+Learn how to start Actors and retrieve their results using the Apify Client.


The guide should make it clear that the client essentially allows doing everything you can do in the console, and running Actors and fetching the results is just the tip of the iceberg.

janbuchar · 2026-02-03T18:08:50Z

docs/01_introduction/quick-start.md

+
+## Step 2: Running your first Actor
+
+To start an Actor, you need its ID (e.g., `john-doe/my-cool-actor`) and an API token. The Actor's ID is a combination of the Actor name and the Actor owner's username. Use the [`ActorClient`](/reference/class/ActorClient) to run the Actor and wait for it to complete. You can run both your own Actors and [Actors from Apify Store](https://docs.apify.com/platform/actors/running/actors-in-store).


It's worth mentioning that the API tab in the store gives you a code snippet for running that specific Actor - https://apify.com/apify/website-content-crawler/api/javascript

janbuchar · 2026-02-03T18:17:54Z

docs/02_concepts/03_error_handling.md

+    if (result.retryable) {
+        // Implement retry logic
+        console.log('This error is retryable. Consider retrying...');
+    }


I'd just drop this - at this point, the client already retried the request extensively.

janbuchar · 2026-02-03T18:18:32Z

docs/02_concepts/03_error_handling.md

+}
+```
+
+## Retry Logic with Exponential Backoff


This section is unnecessary, the client does this out of the box.

janbuchar · 2026-02-03T18:20:29Z

docs/02_concepts/03_error_handling.md

+## Validation Errors
+
+The API returns validation errors when input doesn't meet requirements:
+
+```js
+try {
+    await client.actors().create({
+        // Missing required 'name' field
+    });
+} catch (error) {
+    if (error.statusCode === 400) {
+        console.error('Validation error:', error.message);
+        // Handle validation failure
+    }
+}
+```
+
+## Graceful Degradation
+
+Implement graceful degradation for non-critical operations:
+
+```js
+async function getActorWithFallback(actorId) {
+    try {
+        return await client.actor(actorId).get();
+    } catch (error) {
+        console.warn(`Failed to fetch actor: ${error.message}`);
+
+        // Return fallback data
+        return {
+            id: actorId,
+            name: 'Unknown Actor',
+            unavailable: true
+        };
+    }
+}
+```
+
+## Debugging Tips
+
+Enable detailed logging to debug errors:
+
+```js
+const client = new ApifyClient({
+    token: 'MY-APIFY-TOKEN',
+    // Add custom request interceptor for debugging
+});
+
+try {
+    await client.actor('my-actor').start();
+} catch (error) {
+    // Log full error details
+    console.error('Full error:', JSON.stringify({
+        message: error.message,
+        statusCode: error.statusCode,
+        type: error.type,
+        clientMethod: error.clientMethod,
+        path: error.path,
+        stack: error.stack
+    }, null, 2));
+}
+```


This is also just filler - the docs don't exist to lecture people on the general principles of working with HTTP APIs in Javascript

janbuchar · 2026-02-03T18:21:55Z

docs/02_concepts/05_pagination.md

+title: 'Pagination'
+---
+
+Most methods named `list` or `listSomething` return a [`Promise<PaginatedList>`](/reference/interface/PaginatedList).


The return values also typically return an AsyncIterator so you can just use a for await (...) loop without worrying about pagination.

janbuchar · 2026-02-03T18:23:07Z

docs/03_guides/01_passing_input_to_actors.md

+---
+
+The fastest way to get results from an Actor is to pass input directly to the `call` function.
+Input can be passed to `call` function and the reference of running Actor (or wait for finish) is available in `runData` variable.


Again, would be great to mention the API tab in the Store - the snippets include a prefilled input object, which is nice

patrikbraborec and others added 3 commits November 27, 2025 13:09

docs: Improve the structure of the docs

52c0dc1

docs: Improve the structure of the docs

9bcd35a

patrikbraborec requested a review from TC-MO as a code owner January 16, 2026 11:02

B4nan requested a review from janbuchar January 20, 2026 15:13

janbuchar reviewed Feb 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Refactor documentation structure and add new guides#824

docs: Refactor documentation structure and add new guides#824
patrikbraborec wants to merge 3 commits intomasterfrom
apify-docs-agent-refactor

patrikbraborec commented Jan 16, 2026

Uh oh!

janbuchar left a comment

Uh oh!

janbuchar Feb 3, 2026

Uh oh!

janbuchar Feb 3, 2026

Uh oh!

janbuchar Feb 3, 2026

Uh oh!

janbuchar Feb 3, 2026

Uh oh!

janbuchar Feb 3, 2026

Uh oh!

janbuchar Feb 3, 2026

Uh oh!

janbuchar Feb 3, 2026

Uh oh!

janbuchar Feb 3, 2026

Uh oh!

janbuchar Feb 3, 2026

Uh oh!

janbuchar Feb 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		## Authentication and Initialization

		To use the client, you need an [API token](https://docs.apify.com/platform/integrations/api#api-token). You can find your token under [Integrations](https://console.apify.com/account/integrations) tab in Apify Console. Copy the token and initialize the client by providing the token (`MY-APIFY-TOKEN`) as a parameter to the `ApifyClient` constructor.


		:::note Resource identification

		The resource ID can be either the `id` of the said resource, or a combination of your `username/resource-name`.


		## Step 2: Running your first Actor

		To start an Actor, you need its ID (e.g., `john-doe/my-cool-actor`) and an API token. The Actor's ID is a combination of the Actor name and the Actor owner's username. Use the [`ActorClient`](/reference/class/ActorClient) to run the Actor and wait for it to complete. You can run both your own Actors and [Actors from Apify Store](https://docs.apify.com/platform/actors/running/actors-in-store).

Conversation

patrikbraborec commented Jan 16, 2026

Summary

Test plan

Uh oh!

janbuchar 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants