From 8e2645ddb13a53f75d97f1ca26f4d33dfea3a0e5 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Tue, 11 Nov 2025 15:46:34 +0100 Subject: [PATCH 1/5] docs: add introduction page --- docs/getting-started.md | 283 +++++++++++++++++++++++++++++++++++++++ docs/index.md | 285 ++++------------------------------------ website/sidebars.js | 2 +- 3 files changed, 310 insertions(+), 260 deletions(-) create mode 100644 docs/getting-started.md diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..fbb4997e --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,283 @@ +--- +sidebar_label: 'Getting started' +title: 'Getting started with JavaScript client' +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +`apify-client` is the official library to access the [Apify REST API](https://docs.apify.com/api/v2) from your JavaScript/TypeScript applications. It runs both in Node.js and browser and provides useful features like automatic retries and convenience functions that improve the experience of using the Apify API. All requests and responses (including errors) are encoded in JSON format with UTF-8 encoding. + +## Pre-requisites + +`apify-client` requires Node.js version 16 or higher. Node.js is available for download on the [official website](https://nodejs.org/). Check for your current node version by running: + +```bash +node -v +``` + +## Installation + +You can install the client via [NPM](https://www.npmjs.com/) or use any other package manager of your choice. + + + + +```bash +npm i apify-client +``` + + + + +```bash +yarn add apify-client +``` + + + + +```bash +pnpm add apify-client +``` + + + + +```bash +bun add apify-client +``` + + + + +## 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. + +```js +// import Apify client +import { ApifyClient } from 'apify-client'; + +// Client initialization with the API token +const client = new ApifyClient({ + token: 'MY-APIFY-TOKEN', +}); +``` + +:::warning Secure access + +The API token is used to authorize your requests to the Apify API. You can be charged for the usage of the underlying services, so do not share your API token with untrusted parties or expose it on the client side of your applications + +::: + +## Quick start + +One of the most common use cases is starting [Actors](https://docs.apify.com/platform/actors) (serverless programs running in the [Apify cloud](https://docs.apify.com/platform)) and getting results from their [datasets](https://docs.apify.com/platform/storage/dataset) (storage) after they finish the job (usually scraping, automation processes or data processing). + +```js +import { ApifyClient } from 'apify-client'; + +const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' }); + +// Starts an Actor and waits for it to finish +const { defaultDatasetId } = await client.actor('username/actor-name').call(); + +// Lists items from the Actor's dataset +const { items } = await client.dataset(defaultDatasetId).listItems(); +``` + +### Running Actors + +To start an Actor, you can use the [ActorClient](/reference/class/ActorClient) (`client.actor()`) and pass the Actor's ID (e.g. `john-doe/my-cool-actor`) to define which Actor you want to run. The Actor's ID is a combination of the username and the Actor owner’s username. You can run both your own Actors and [Actors from Apify Store](https://docs.apify.com/platform/actors/running/actors-in-store). + +#### Passing input to the Actor + +To define the Actor's input, you can pass an object to the [`call()`](/reference/class/ActorClient#call) method. The input object can be any JSON object that the Actor expects (respects the Actor's [input schema](https://docs.apify.com/platform/actors/development/actor-definition/input-schema)). The input object is used to pass configuration to the Actor, such as URLs to scrape, search terms, or any other data. + +```js +import { ApifyClient } from 'apify-client'; + +const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' }); + +// Runs an Actor with an input and waits for it to finish. +const { defaultDatasetId } = await client.actor('username/actor-name').call({ + some: 'input', +}); +``` + +### Getting results from the dataset + +To get the results from the dataset, you can use the [DatasetClient](/reference/class/DatasetClient) (`client.dataset()`) and [`listItems()`](/reference/class/DatasetClient#listItems) method. You need to pass the dataset ID to define which dataset you want to access. You can get the dataset ID from the Actor's run object (represented by `defaultDatasetId`). + +```js +import { ApifyClient } from 'apify-client'; + +const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' }); + +// Lists items from the Actor's dataset. +const { items } = await client.dataset('dataset-id').listItems(); +``` + +:::note Dataset access + +Running an Actor might take time, depending on the Actor's complexity and the amount of data it processes. If you want only to get data and have an immediate response you should access the existing dataset of the finished [Actor run](https://docs.apify.com/platform/actors/running/runs-and-builds#runs). + +::: + +## Usage concepts + +The `ApifyClient` interface follows a generic pattern that applies to all of its components. By calling individual methods of `ApifyClient`, specific clients that target individual API resources are created. There are two types of those clients: + +- [`actorClient`](/reference/class/ActorClient): a client for the management of a single resource +- [`actorCollectionClient`](/reference/class/ActorCollectionClient): a client for the collection of resources + +```js +import { ApifyClient } from 'apify-client'; + +const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' }); + +// Collection clients do not require a parameter. +const actorCollectionClient = client.actors(); +// Creates an actor with the name: my-actor. +const myActor = await actorCollectionClient.create({ name: 'my-actor-name' }); +// List all your used Actors (both own and from Apify Store) +const { items } = await actorCollectionClient.list(); +``` + +:::note Resource identification + +The resource ID can be either the `id` of the said resource, or a combination of your `username/resource-name`. + +::: + +```js +import { ApifyClient } from 'apify-client'; + +const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' }); + +// Resource clients accept an ID of the resource. +const actorClient = client.actor('username/actor-name'); +// Fetches the john-doe/my-actor object from the API. +const myActor = await actorClient.get(); +// Starts the run of john-doe/my-actor and returns the Run object. +const myActorRun = await actorClient.start(); +``` + +### Nested clients + +Sometimes clients return other clients. That's to simplify working with nested collections, such as runs of a given Actor. + +```js +import { ApifyClient } from 'apify-client'; + +const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' }); + +const actorClient = client.actor('username/actor-name'); +const runsClient = actorClient.runs(); +// Lists the last 10 runs of your Actor. +const { items } = await runsClient.list({ + limit: 10, + desc: true, +}); + +// Select the last run of your Actor that finished +// with a SUCCEEDED status. +const lastSucceededRunClient = actorClient.lastRun({ status: 'SUCCEEDED' }); +// Fetches items from the run's dataset. +const { items } = await lastSucceededRunClient.dataset().listItems(); +``` + +The quick access to `dataset` and other storage directly from the run client can be used with the [`lastRun()`](/reference/class/ActorClient#lastRun) method. + +## Features + +Based on the endpoint, the client automatically extracts the relevant data and returns it in the expected format. Date strings are automatically converted to `Date` objects. For exceptions, the client throws an [`ApifyApiError`](/reference/class/ApifyApiError), which wraps the plain JSON errors returned by API and enriches them with other contexts for easier debugging. + +```js +import { ApifyClient } from 'apify-client'; + +const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' }); + +try { + const { items } = await client.dataset('non-existing-dataset-id').listItems(); +} catch (error) { + // The error is an instance of ApifyApiError + const { message, type, statusCode, clientMethod, path } = error; + // Log error for easier debugging + console.log({ message, statusCode, clientMethod, type }); +} +``` + +### Retries with exponential backoff + +Network communication sometimes fails. That's a given. The client will automatically retry requests that failed due to a network error, an internal error of the Apify API (HTTP 500+), or a rate limit error (HTTP 429). By default, it will retry up to 8 times. The first retry will be attempted after ~500ms, the second after ~1000ms, and so on. You can configure those parameters using the `maxRetries` and `minDelayBetweenRetriesMillis` options of the `ApifyClient` constructor. + +```js +import { ApifyClient } from 'apify-client'; + +const client = new ApifyClient({ + token: 'MY-APIFY-TOKEN', + maxRetries: 8, + minDelayBetweenRetriesMillis: 500, // 0.5s + timeoutSecs: 360, // 6 mins +}); +``` + +### Convenience functions and options + +Some actions can't be performed by the API itself, such as indefinite waiting for an Actor run to finish (because of network timeouts). The client provides convenient `call()` and `waitForFinish()` functions that do that. If the limit is reached, the returned promise is resolved to a run object that will have status `READY` or `RUNNING` and it will not contain the Actor run output. + +[Key-value store](https://docs.apify.com/platform/storage/key-value-store) records can be retrieved as objects, buffers, or streams via the respective options, dataset items can be fetched as individual objects or serialized data. + +```js +import { ApifyClient } from 'apify-client'; + +const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' }); + +// Starts an Actor and waits for it to finish. +const finishedActorRun = await client.actor('username/actor-name').call(); + +// Starts an Actor and waits maximum 60s for the finish +const { status } = await client.actor('username/actor-name').start({ + waitForFinish: 60, // 1 minute +}); +``` + +### Pagination + +Most methods named `list` or `listSomething` return a [`Promise`](/reference/interface/PaginatedList). There are some exceptions though, like `listKeys` or `listHead` which paginate differently. The results you're looking for are always stored under `items` and you can use the `limit` property to get only a subset of results. Other props are also available, depending on the method. + +```js +import { ApifyClient } from 'apify-client'; + +const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' }); + +// Resource clients accept an ID of the resource. +const datasetClient = client.dataset('dataset-id'); + +// Number of items per page +const limit = 1000; +// Initial offset +let offset = 0; +// Array to store all items +let allItems = []; + +while (true) { + const { items, total } = await datasetClient.listItems({ limit, offset }); + + console.log(`Fetched ${items.length} items`); + + // Merge new items with other already loaded items + allItems.push(...items); + + // If there are no more items to fetch, exit the loading + if (offset + limit >= total) { + break; + } + + offset += limit; +} + +console.log(`Overall fetched ${allItems.length} items`); +``` diff --git a/docs/index.md b/docs/index.md index 2324a8be..d4fede6c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,283 +1,50 @@ --- -sidebar_label: 'Getting started' +sidebar_label: 'Introduction' title: 'Apify API client for JavaScript' --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -`apify-client` is the official library to access the [Apify REST API](https://docs.apify.com/api/v2) from your JavaScript/TypeScript applications. It runs both in Node.js and browser and provides useful features like automatic retries and convenience functions that improve the experience of using the Apify API. All requests and responses (including errors) are encoded in JSON format with UTF-8 encoding. +`apify-client` is the official library to access the [Apify REST API](https://docs.apify.com/api/v2) from your JavaScript/TypeScript applications. It runs both in Node.js and browser and provides useful features like automatic retries and convenience functions that improve the experience of using the Apify API. -## Pre-requisites +The client simplifies interaction with the Apify Platform by providing: -`apify-client` requires Node.js version 16 or higher. Node.js is available for download on the [official website](https://nodejs.org/). Check for your current node version by running: +- Intuitive methods for working with [Actors](https://docs.apify.com/platform/actors), [datasets](https://docs.apify.com/platform/storage/dataset), [key-value stores](https://docs.apify.com/platform/storage/key-value-store), and other Apify resources +- Intelligent parsing of API responses and rich error messages for debugging +- Built-in [exponential backoff](./getting-started#retries-with-exponential-backoff) for failed requests +- Full TypeScript support with comprehensive type definitions +- Cross-platform compatibility in [Node.js](https://nodejs.org/) (v16+) and modern browsers -```bash -node -v -``` - -## Installation - -You can install the client via [NPM](https://www.npmjs.com/) or use any other package manager of your choice. - - - - -```bash -npm i apify-client -``` - - - +All requests and responses (including errors) are encoded in JSON format with UTF-8 encoding. -```bash -yarn add apify-client -``` - - - - -```bash -pnpm add apify-client -``` - - - - -```bash -bun add apify-client -``` +> For installation instructions, see the [Getting Started Guide](./getting-started.md). - - +## Quick Example -## Authentication and Initialization +Here's a simple example showing how to run an Actor and retrieve its results: -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. - -```js -// import Apify client +```javascript import { ApifyClient } from 'apify-client'; -// Client initialization with the API token +// Initialize the client with your API token const client = new ApifyClient({ - token: 'MY-APIFY-TOKEN', -}); -``` - -:::warning Secure access - -The API token is used to authorize your requests to the Apify API. You can be charged for the usage of the underlying services, so do not share your API token with untrusted parties or expose it on the client side of your applications - -::: - -## Quick start - -One of the most common use cases is starting [Actors](https://docs.apify.com/platform/actors) (serverless programs running in the [Apify cloud](https://docs.apify.com/platform)) and getting results from their [datasets](https://docs.apify.com/platform/storage/dataset) (storage) after they finish the job (usually scraping, automation processes or data processing). - -```js -import { ApifyClient } from 'apify-client'; - -const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' }); - -// Starts an Actor and waits for it to finish -const { defaultDatasetId } = await client.actor('username/actor-name').call(); - -// Lists items from the Actor's dataset -const { items } = await client.dataset(defaultDatasetId).listItems(); -``` - -### Running Actors - -To start an Actor, you can use the [ActorClient](/reference/class/ActorClient) (`client.actor()`) and pass the Actor's ID (e.g. `john-doe/my-cool-actor`) to define which Actor you want to run. The Actor's ID is a combination of the username and the Actor owner’s username. You can run both your own Actors and [Actors from Apify Store](https://docs.apify.com/platform/actors/running/actors-in-store). - -#### Passing input to the Actor - -To define the Actor's input, you can pass an object to the [`call()`](/reference/class/ActorClient#call) method. The input object can be any JSON object that the Actor expects (respects the Actor's [input schema](https://docs.apify.com/platform/actors/development/actor-definition/input-schema)). The input object is used to pass configuration to the Actor, such as URLs to scrape, search terms, or any other data. - -```js -import { ApifyClient } from 'apify-client'; - -const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' }); - -// Runs an Actor with an input and waits for it to finish. -const { defaultDatasetId } = await client.actor('username/actor-name').call({ - some: 'input', -}); -``` - -### Getting results from the dataset - -To get the results from the dataset, you can use the [DatasetClient](/reference/class/DatasetClient) (`client.dataset()`) and [`listItems()`](/reference/class/DatasetClient#listItems) method. You need to pass the dataset ID to define which dataset you want to access. You can get the dataset ID from the Actor's run object (represented by `defaultDatasetId`). - -```js -import { ApifyClient } from 'apify-client'; - -const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' }); - -// Lists items from the Actor's dataset. -const { items } = await client.dataset('dataset-id').listItems(); -``` - -:::note Dataset access - -Running an Actor might take time, depending on the Actor's complexity and the amount of data it processes. If you want only to get data and have an immediate response you should access the existing dataset of the finished [Actor run](https://docs.apify.com/platform/actors/running/runs-and-builds#runs). - -::: - -## Usage concepts - -The `ApifyClient` interface follows a generic pattern that applies to all of its components. By calling individual methods of `ApifyClient`, specific clients that target individual API resources are created. There are two types of those clients: - -- [`actorClient`](/reference/class/ActorClient): a client for the management of a single resource -- [`actorCollectionClient`](/reference/class/ActorCollectionClient): a client for the collection of resources - -```js -import { ApifyClient } from 'apify-client'; - -const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' }); - -// Collection clients do not require a parameter. -const actorCollectionClient = client.actors(); -// Creates an actor with the name: my-actor. -const myActor = await actorCollectionClient.create({ name: 'my-actor-name' }); -// List all your used Actors (both own and from Apify Store) -const { items } = await actorCollectionClient.list(); -``` - -:::note Resource identification - -The resource ID can be either the `id` of the said resource, or a combination of your `username/resource-name`. - -::: - -```js -import { ApifyClient } from 'apify-client'; - -const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' }); - -// Resource clients accept an ID of the resource. -const actorClient = client.actor('username/actor-name'); -// Fetches the john-doe/my-actor object from the API. -const myActor = await actorClient.get(); -// Starts the run of john-doe/my-actor and returns the Run object. -const myActorRun = await actorClient.start(); -``` - -### Nested clients - -Sometimes clients return other clients. That's to simplify working with nested collections, such as runs of a given Actor. - -```js -import { ApifyClient } from 'apify-client'; - -const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' }); - -const actorClient = client.actor('username/actor-name'); -const runsClient = actorClient.runs(); -// Lists the last 10 runs of your Actor. -const { items } = await runsClient.list({ - limit: 10, - desc: true, + token: 'YOUR-APIFY-TOKEN', }); -// Select the last run of your Actor that finished -// with a SUCCEEDED status. -const lastSucceededRunClient = actorClient.lastRun({ status: 'SUCCEEDED' }); -// Fetches items from the run's dataset. -const { items } = await lastSucceededRunClient.dataset().listItems(); -``` - -The quick access to `dataset` and other storage directly from the run client can be used with the [`lastRun()`](/reference/class/ActorClient#lastRun) method. - -## Features - -Based on the endpoint, the client automatically extracts the relevant data and returns it in the expected format. Date strings are automatically converted to `Date` objects. For exceptions, the client throws an [`ApifyApiError`](/reference/class/ApifyApiError), which wraps the plain JSON errors returned by API and enriches them with other contexts for easier debugging. - -```js -import { ApifyClient } from 'apify-client'; - -const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' }); - -try { - const { items } = await client.dataset('non-existing-dataset-id').listItems(); -} catch (error) { - // The error is an instance of ApifyApiError - const { message, type, statusCode, clientMethod, path } = error; - // Log error for easier debugging - console.log({ message, statusCode, clientMethod, type }); -} -``` - -### Retries with exponential backoff - -Network communication sometimes fails. That's a given. The client will automatically retry requests that failed due to a network error, an internal error of the Apify API (HTTP 500+), or a rate limit error (HTTP 429). By default, it will retry up to 8 times. The first retry will be attempted after ~500ms, the second after ~1000ms, and so on. You can configure those parameters using the `maxRetries` and `minDelayBetweenRetriesMillis` options of the `ApifyClient` constructor. - -```js -import { ApifyClient } from 'apify-client'; - -const client = new ApifyClient({ - token: 'MY-APIFY-TOKEN', - maxRetries: 8, - minDelayBetweenRetriesMillis: 500, // 0.5s - timeoutSecs: 360, // 6 mins +// Start an Actor and wait for it to finish +const run = await client.actor('apify/web-scraper').call({ + startUrls: [{ url: 'https://example.com' }], + maxCrawlPages: 10, }); -``` - -### Convenience functions and options - -Some actions can't be performed by the API itself, such as indefinite waiting for an Actor run to finish (because of network timeouts). The client provides convenient `call()` and `waitForFinish()` functions that do that. If the limit is reached, the returned promise is resolved to a run object that will have status `READY` or `RUNNING` and it will not contain the Actor run output. - -[Key-value store](https://docs.apify.com/platform/storage/key-value-store) records can be retrieved as objects, buffers, or streams via the respective options, dataset items can be fetched as individual objects or serialized data. - -```js -import { ApifyClient } from 'apify-client'; - -const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' }); - -// Starts an Actor and waits for it to finish. -const finishedActorRun = await client.actor('username/actor-name').call(); -// Starts an Actor and waits maximum 60s for the finish -const { status } = await client.actor('username/actor-name').start({ - waitForFinish: 60, // 1 minute -}); +// Get results from the Actor's dataset +const { items } = await client.dataset(run.defaultDatasetId).listItems(); +console.log(items); ``` -### Pagination - -Most methods named `list` or `listSomething` return a [`Promise`](/reference/interface/PaginatedList). There are some exceptions though, like `listKeys` or `listHead` which paginate differently. The results you're looking for are always stored under `items` and you can use the `limit` property to get only a subset of results. Other props are also available, depending on the method. - -```js -import { ApifyClient } from 'apify-client'; - -const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' }); - -// Resource clients accept an ID of the resource. -const datasetClient = client.dataset('dataset-id'); - -// Number of items per page -const limit = 1000; -// Initial offset -let offset = 0; -// Array to store all items -let allItems = []; +## Next Steps -while (true) { - const { items, total } = await datasetClient.listItems({ limit, offset }); - - console.log(`Fetched ${items.length} items`); - - // Merge new items with other already loaded items - allItems.push(...items); - - // If there are no more items to fetch, exit the loading - if (offset + limit >= total) { - break; - } - - offset += limit; -} - -console.log(`Overall fetched ${allItems.length} items`); -``` +- [Getting Started Guide](./getting-started.md) - Detailed setup and usage instructions +- [API Reference](../reference) - Complete API documentation +- [Examples](./examples) - Code examples for common use cases diff --git a/website/sidebars.js b/website/sidebars.js index 3dacf339..57bb5430 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -3,7 +3,7 @@ module.exports = [ { type: 'category', label: 'API Client', - items: ['index', 'examples/index'], + items: ['index', 'getting-started', 'examples/index'], }, ], ]; From ecf9b15a4305f63acabe48e86fb65d01a4f60227 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Wed, 12 Nov 2025 13:46:48 +0100 Subject: [PATCH 2/5] docs: fix page naming --- docs/{getting-started.md => getting_started.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{getting-started.md => getting_started.md} (100%) diff --git a/docs/getting-started.md b/docs/getting_started.md similarity index 100% rename from docs/getting-started.md rename to docs/getting_started.md From d747b920fbe920e4fb6fefc715925301466179fe Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Thu, 13 Nov 2025 10:41:03 +0100 Subject: [PATCH 3/5] docs: fix issues and rename page --- docs/{getting_started.md => getting-started.md} | 0 docs/index.md | 6 +++--- 2 files changed, 3 insertions(+), 3 deletions(-) rename docs/{getting_started.md => getting-started.md} (100%) diff --git a/docs/getting_started.md b/docs/getting-started.md similarity index 100% rename from docs/getting_started.md rename to docs/getting-started.md diff --git a/docs/index.md b/docs/index.md index d4fede6c..0a557b54 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,5 @@ --- -sidebar_label: 'Introduction' +sidebar_label: 'Overview' title: 'Apify API client for JavaScript' --- @@ -12,7 +12,7 @@ The client simplifies interaction with the Apify Platform by providing: - Intuitive methods for working with [Actors](https://docs.apify.com/platform/actors), [datasets](https://docs.apify.com/platform/storage/dataset), [key-value stores](https://docs.apify.com/platform/storage/key-value-store), and other Apify resources - Intelligent parsing of API responses and rich error messages for debugging -- Built-in [exponential backoff](./getting-started#retries-with-exponential-backoff) for failed requests +- Built-in [exponential backoff](./getting-started.md#retries-with-exponential-backoff) for failed requests - Full TypeScript support with comprehensive type definitions - Cross-platform compatibility in [Node.js](https://nodejs.org/) (v16+) and modern browsers @@ -45,6 +45,6 @@ console.log(items); ## Next Steps -- [Getting Started Guide](./getting-started.md) - Detailed setup and usage instructions +- [x Started Guide](./getting-started.md) - Detailed setup and usage instructions - [API Reference](../reference) - Complete API documentation - [Examples](./examples) - Code examples for common use cases From af3296742c2b33455ff7639c0c4365db54a5efe7 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Tue, 25 Nov 2025 13:12:22 +0100 Subject: [PATCH 4/5] docs: apply review comments --- docs/getting-started.md | 28 ++++++++++++++++------------ docs/index.md | 10 +++++----- 2 files changed, 21 insertions(+), 17 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index fbb4997e..b0ea82fb 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -6,11 +6,11 @@ title: 'Getting started with JavaScript client' import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -`apify-client` is the official library to access the [Apify REST API](https://docs.apify.com/api/v2) from your JavaScript/TypeScript applications. It runs both in Node.js and browser and provides useful features like automatic retries and convenience functions that improve the experience of using the Apify API. All requests and responses (including errors) are encoded in JSON format with UTF-8 encoding. +The Apify API client is the official library to access the [Apify REST API](https://docs.apify.com/api/v2) from your JavaScript/TypeScript applications. It runs both in Node.js and browser and provides useful features like automatic retries and convenience functions that improve the experience of using the Apify API. All requests and responses (including errors) are encoded in JSON format with UTF-8 encoding. ## Pre-requisites -`apify-client` requires Node.js version 16 or higher. Node.js is available for download on the [official website](https://nodejs.org/). Check for your current node version by running: +`apify-client` requires Node.js version 16 or higher. Node.js is available for download on the [official website](https://nodejs.org/). Check for your current Node.js version by running: ```bash node -v @@ -18,7 +18,7 @@ node -v ## Installation -You can install the client via [NPM](https://www.npmjs.com/) or use any other package manager of your choice. +You can install the client via [NPM](https://www.npmjs.com/) or any other package manager of your choice. @@ -73,7 +73,7 @@ The API token is used to authorize your requests to the Apify API. You can be ch ## Quick start -One of the most common use cases is starting [Actors](https://docs.apify.com/platform/actors) (serverless programs running in the [Apify cloud](https://docs.apify.com/platform)) and getting results from their [datasets](https://docs.apify.com/platform/storage/dataset) (storage) after they finish the job (usually scraping, automation processes or data processing). +One of the most common use cases is starting [Actors](https://docs.apify.com/platform/actors) (serverless programs running in the [Apify platform](https://docs.apify.com/platform)) and getting results from their [datasets](https://docs.apify.com/platform/storage/dataset) after they finish the job (either scraping, automation processes or data processing). ```js import { ApifyClient } from 'apify-client'; @@ -89,11 +89,11 @@ const { items } = await client.dataset(defaultDatasetId).listItems(); ### Running Actors -To start an Actor, you can use the [ActorClient](/reference/class/ActorClient) (`client.actor()`) and pass the Actor's ID (e.g. `john-doe/my-cool-actor`) to define which Actor you want to run. The Actor's ID is a combination of the username and the Actor owner’s username. You can run both your own Actors and [Actors from Apify Store](https://docs.apify.com/platform/actors/running/actors-in-store). +To start an Actor, call the [`client.actor()`](/reference/class/ActorClient) method with the Actor's ID (e.g. `john-doe/my-cool-actor`). The Actor's ID is a combination of the Actor name and the Actor owner's username. You can run both your own Actors and Actors from Apify Store. #### Passing input to the Actor -To define the Actor's input, you can pass an object to the [`call()`](/reference/class/ActorClient#call) method. The input object can be any JSON object that the Actor expects (respects the Actor's [input schema](https://docs.apify.com/platform/actors/development/actor-definition/input-schema)). The input object is used to pass configuration to the Actor, such as URLs to scrape, search terms, or any other data. +To define the Actor's input, call the [`call()`](/reference/class/ActorClient#call) method with a JSON object that matches the Actor's [input schema](https://docs.apify.com/platform/actors/development/actor-definition/input-schema). The input can include URLs to scrape, search terms, or other configuration data. ```js import { ApifyClient } from 'apify-client'; @@ -108,7 +108,7 @@ const { defaultDatasetId } = await client.actor('username/actor-name').call({ ### Getting results from the dataset -To get the results from the dataset, you can use the [DatasetClient](/reference/class/DatasetClient) (`client.dataset()`) and [`listItems()`](/reference/class/DatasetClient#listItems) method. You need to pass the dataset ID to define which dataset you want to access. You can get the dataset ID from the Actor's run object (represented by `defaultDatasetId`). +To get the results from the dataset, call the [`client.dataset()`](/reference/class/DatasetClient) method with the dataset ID, then call [`listItems()`](/reference/class/DatasetClient#listItems) to retrieve the data. You can get the dataset ID from the Actor's run object (represented by `defaultDatasetId`). ```js import { ApifyClient } from 'apify-client'; @@ -127,10 +127,10 @@ Running an Actor might take time, depending on the Actor's complexity and the am ## Usage concepts -The `ApifyClient` interface follows a generic pattern that applies to all of its components. By calling individual methods of `ApifyClient`, specific clients that target individual API resources are created. There are two types of those clients: +The `ApifyClient` interface follows a generic pattern that applies to all of its components. By calling individual methods of `ApifyClient`, specific clients that target individual API resources are created. There are two types of those clients: -- [`actorClient`](/reference/class/ActorClient): a client for the management of a single resource -- [`actorCollectionClient`](/reference/class/ActorCollectionClient): a client for the collection of resources +- [`ActorClient`](/reference/class/ActorClient): a client for the management of a single resource +- [`ActorCollectionClient`](/reference/class/ActorCollectionClient): a client for the collection of resources ```js import { ApifyClient } from 'apify-client'; @@ -211,7 +211,9 @@ try { ### Retries with exponential backoff -Network communication sometimes fails. That's a given. The client will automatically retry requests that failed due to a network error, an internal error of the Apify API (HTTP 500+), or a rate limit error (HTTP 429). By default, it will retry up to 8 times. The first retry will be attempted after ~500ms, the second after ~1000ms, and so on. You can configure those parameters using the `maxRetries` and `minDelayBetweenRetriesMillis` options of the `ApifyClient` constructor. +The client automatically retries requests that fail due to network errors, Apify API internal errors (HTTP 500+), or rate limit errors (HTTP 429). By default, the client retries up to 8 times with exponential backoff starting at 500ms. + +To configure retry behavior, set the `maxRetries` and `minDelayBetweenRetriesMillis` options in the `ApifyClient` constructor: ```js import { ApifyClient } from 'apify-client'; @@ -246,7 +248,9 @@ const { status } = await client.actor('username/actor-name').start({ ### Pagination -Most methods named `list` or `listSomething` return a [`Promise`](/reference/interface/PaginatedList). There are some exceptions though, like `listKeys` or `listHead` which paginate differently. The results you're looking for are always stored under `items` and you can use the `limit` property to get only a subset of results. Other props are also available, depending on the method. +Methods that return lists (such as `list()` or `listSomething()`) return a [`PaginatedList`](/reference/interface/PaginatedList) object. Exceptions include `listKeys()` and `listHead()`, which use different pagination mechanisms. + +The list results are stored in the `items` property. Use the `limit` parameter to retrieve a specific number of results. Additional properties vary by method—see the method reference for details. ```js import { ApifyClient } from 'apify-client'; diff --git a/docs/index.md b/docs/index.md index 0a557b54..7234fb23 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,15 +6,15 @@ title: 'Apify API client for JavaScript' import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -`apify-client` is the official library to access the [Apify REST API](https://docs.apify.com/api/v2) from your JavaScript/TypeScript applications. It runs both in Node.js and browser and provides useful features like automatic retries and convenience functions that improve the experience of using the Apify API. +The Apify API client is the official library to access the [Apify REST API](https://docs.apify.com/api/v2) from your JavaScript/TypeScript applications. It runs both in Node.js and browser and provides useful features like automatic retries and convenience functions that improve the experience of using the Apify API. -The client simplifies interaction with the Apify Platform by providing: +The client simplifies interaction with the Apify platform by providing: - Intuitive methods for working with [Actors](https://docs.apify.com/platform/actors), [datasets](https://docs.apify.com/platform/storage/dataset), [key-value stores](https://docs.apify.com/platform/storage/key-value-store), and other Apify resources - Intelligent parsing of API responses and rich error messages for debugging - Built-in [exponential backoff](./getting-started.md#retries-with-exponential-backoff) for failed requests - Full TypeScript support with comprehensive type definitions -- Cross-platform compatibility in [Node.js](https://nodejs.org/) (v16+) and modern browsers +- Cross-platform compatibility in [Node.js](https://nodejs.org/) v16+ and modern browsers All requests and responses (including errors) are encoded in JSON format with UTF-8 encoding. @@ -22,7 +22,7 @@ All requests and responses (including errors) are encoded in JSON format with UT ## Quick Example -Here's a simple example showing how to run an Actor and retrieve its results: +Here's an example showing how to run an Actor and retrieve its results: ```javascript import { ApifyClient } from 'apify-client'; @@ -45,6 +45,6 @@ console.log(items); ## Next Steps -- [x Started Guide](./getting-started.md) - Detailed setup and usage instructions +- [Getting Started Guide](./getting-started.md) - Detailed setup and usage instructions - [API Reference](../reference) - Complete API documentation - [Examples](./examples) - Code examples for common use cases From 95bc56ce03dc2ea252f6aa599cc86c94f663001a Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Fri, 28 Nov 2025 14:10:22 +0100 Subject: [PATCH 5/5] review changes --- docs/index.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/index.md b/docs/index.md index 7234fb23..df1ffab7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,9 +18,9 @@ The client simplifies interaction with the Apify platform by providing: All requests and responses (including errors) are encoded in JSON format with UTF-8 encoding. -> For installation instructions, see the [Getting Started Guide](./getting-started.md). +> For installation instructions, check the [Getting Started Guide](./getting-started.md). -## Quick Example +## Quick example Here's an example showing how to run an Actor and retrieve its results: @@ -43,7 +43,9 @@ const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items); ``` -## Next Steps +> You can find your API token in the [Integrations section](https://console.apify.com/account/integrations) of Apify Console. See the [Getting Started Guide](./getting-started.md#authentication-and-initialization) for more details on authentication. + +## Next steps - [Getting Started Guide](./getting-started.md) - Detailed setup and usage instructions - [API Reference](../reference) - Complete API documentation