diff --git a/documentation/quickstart.md b/documentation/quickstart.md index dde0930c6..3d23ea122 100644 --- a/documentation/quickstart.md +++ b/documentation/quickstart.md @@ -1,4 +1,4 @@ -# Quick start guide +# Quick Start Guide ## Getting and posting data with promises @@ -11,19 +11,24 @@ const url = 'https://httpbin.org/anything'; const response = await got(url); ``` -The call returns a Promise<[Response](3-streams.md#response-1)>. If the body contains json, it can be retreived directly: +The call returns a Promise<[Response](3-streams.md#response-1)>. 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 [got.text](1-promise.md#promisetext) 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', @@ -39,15 +44,20 @@ 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 @@ -55,24 +65,29 @@ The [Stream API](3-streams.md) allows to leverage [Node.js Streams](https://node ```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'; @@ -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); } ``` @@ -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 @@ -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 @@ -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, + ], }, }; @@ -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:. \ No newline at end of file +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:.