Skip to content

Commit

Permalink
Update quickstart.md
Browse files Browse the repository at this point in the history
  • Loading branch information
sindresorhus authored Jul 5, 2022
1 parent 2dd6cef commit a4fed5a
Showing 1 changed file with 61 additions and 34 deletions.
95 changes: 61 additions & 34 deletions documentation/quickstart.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Quick start guide
# Quick Start Guide

## Getting and posting data with promises

Expand All @@ -11,19 +11,24 @@ const url = 'https://httpbin.org/anything';
const response = await got(url);
```

The call returns a <code>Promise<[Response](3-streams.md#response-1)></code>. If the body contains json, it can be retreived directly:
The call returns a <code>Promise<[Response](3-streams.md#response-1)></code>. If the body contains JSON, it can be retrieved directly:

```js
import got from 'got';

const url = 'https://httpbin.org/anything';
const data = await got(url).json();
```

The similar <code>[got.text](1-promise.md#promisetext)</code> method returns plain text.

All `got` methods accepts an options object for passing extra informations, such as headers:
All `got` methods accept an options object for passing extra configuration, such as headers:

```js
import got from 'got';

const url = 'https://httpbin.org/anything';

const options = {
headers: {
'Custom-Header': 'Quick start',
Expand All @@ -39,40 +44,50 @@ const data = await got(url, options).json();
A `POST` request is very similar:

```js
import got from 'got';

const url = 'https://httpbin.org/anything';

const options = {
json: { documentName: 'Quick Start' },
json: {
documentName: 'Quick Start',
},
};

const data = await got.post(url, options);
```

The request body is passed in the options object, `json` property will automatically set headers accordingly. Custom headers can be added exactly as above.
The request body is passed in the options object. The `json` property will automatically set headers accordingly. Custom headers can be added exactly as above.

## Using streams

The [Stream API](3-streams.md) allows to leverage [Node.js Streams](https://nodejs.dev/learn/nodejs-streams) capabilities:

```js
import got from 'got';
import fs from 'fs';
import { pipeline } from 'stream';
import fs from 'node:fs';
import {pipeline} from 'node:stream';

const url = 'https://httpbin.org/anything';

const options = {
json: { documentName: 'Quick Start' },
json: {
documentName: 'Quick Start',
},
};

const gotStream = got.stream.post(url, options);

const outStream = fs.createWriteStream('anything.json');

pipeline(gotStream, outStream, error => {
if (error) console.error(error.message);
if (error) console.error(error.message);
});
```

## Options

Options can be set at client level and reused in subsequent queries:
Options can be set at the client level and reused in subsequent queries:

```js
import got from 'got';
Expand All @@ -89,27 +104,27 @@ const client = got.extend(options);
export default client;
```

Some noticable common options are (opinionated :blush:):
- [searchParams](./2-options.md#searchparams): a query string object.
- [prefixUrl](./2-options.md#prefixurl): prepended to query pathes. Pathes must be relative to prefix, i.e. not begin with a `/`.
- [method](./2-options.md#method): the HTTP method name.
- [headers](./2-options.md#headers): query headers.
- [json](./2-options.md#json): JSON body.
- [form](./2-options.md#form): a form query string object.
See documentation for other [options](./2-options.md#options).
Some noticable common options are:
- [`searchParams`](2-options.md#searchparams): A query string object.
- [`prefixUrl`](2-options.md#prefixurl): Prepended to query pathes. Pathes must be relative to prefix, i.e. not begin with a `/`.
- [`method`](2-options.md#method): The HTTP method name.
- [`headers`](2-options.md#headers): Query headers.
- [`json`](2-options.md#json): JSON body.
- [`form`](2-options.md#form): A form query string object.

See documentation for other [options](2-options.md#options).

## Errors

Both Promise and Stream APIs throws error with metadata. They are handled according to the API used.
Both Promise and Stream APIs throw errors with metadata.

```js
import got from 'got';

try {
const data = await got.get('https://httpbin.org/status/404');
const data = await got.get('https://httpbin.org/status/404');
} catch (error) {
console.error(error.message);
console.error(error.message);
}
```

Expand All @@ -123,22 +138,28 @@ const stream = got.stream
});
```

## Miscalleneous
## Miscellaneous

The HTTP method name can also be given as an option, this may be convenient when it is known only at runtime:

```js
import got from 'got';

const url = 'https://httpbin.org/anything';

const method = 'POST';

const options = {
json: { documentName: 'Quick Start' },
method,
json: {
documentName: 'Quick Start',
},
};

const data = await got(url, options);
```

For most applications, http client just do `GET` and `POST` queries (`PUT`, `PATCH` or `DELETE` methods work similarly).
For most apps, HTTP clients just do `GET` and `POST` queries (`PUT`, `PATCH` or `DELETE` methods work similarly).
The following sections will give some pointers to more advanced usage.

### Timeouts
Expand All @@ -159,22 +180,26 @@ const client = got.extend(options);
export default client;
```

The above set a global timeout of 10000 ms for all requests issued by the exported `client`. Like all options, timeouts can also be set at request level. See [timeout options](./6-timeout.md#timeout-options).
The above sets a global timeout of 10000 milliseconds for all requests issued by the exported `client`. Like all options, timeouts can also be set at the request level. See the [`timeout` option](6-timeout.md#timeout-options).

### Retries

A failed request is retried twice, retry policy may be tuned with a [`retry`](./7-retry.md#retry) option object.
A failed request is retried twice, retry policy may be tuned with a [`retry`](7-retry.md#retry) options object.

```js
import got from 'got';

const options = {
retry: {
limit: 5,
errorCodes: ['ETIMEDOUT'],
errorCodes: [
'ETIMEDOUT'
],
},
};
```

Retries with stream are a little trickier, see [`stream.on('retry', ...)`](./3-streams.md#streamonretry-).
Retries with stream are a little trickier, see [`stream.on('retry', )`](3-streams.md#streamonretry-).

### Hooks

Expand All @@ -184,12 +209,14 @@ Hooks are custom functions called on some request events:
import got from 'got';

const logRetry = (error, retryCount) => {
console.error(`Retrying after error ${error.code}, retry #: ${retryCount}`);
console.error(`Retrying after error ${error.code}, retry #: ${retryCount}`);
};

const options = {
hooks: {
beforeRetry: [logRetry]
beforeRetry: [
logRetry,
],
},
};

Expand All @@ -198,9 +225,9 @@ const client = got.extend(options);
export default client;
```

*Note that handlers are given as arrays*, thus multiple handlers can be given. See documentation for other possible [hooks](./9-hooks.md#hooks-api).
*Note that handlers are given as arrays*, thus multiple handlers can be given. See documentation for other possible [hooks](9-hooks.md#hooks-api).

### Going further

There's a lot more to discover in the [documentation](../readme.md#documentation) and [tips](./tips.md#tips).
Among others, `Got` can handle [cookies](./tips.md#cookies), [pagination](./4-pagination.md#pagination-api), [cache](./cache.md#cache). Read the doc before implementing something that is already done by `Got` :innocent:.
There is a lot more to discover in the [documentation](../readme.md#documentation) and [tips](tips.md#tips).
Among others, `Got` can handle [cookies](tips.md#cookies), [pagination](4-pagination.md#pagination-api), [cache](cache.md#cache). Read the documentation before implementing something that is already done by `Got` :innocent:.

0 comments on commit a4fed5a

Please sign in to comment.