Skip to content

Commit 40e7be8

Browse files
jasonsaaymanJSap0914
jasonsaayman
and
JSap0914
authored
docs: clarifies that request data is request-specific in axios (#11025)
Co-authored-by: JSap0914 <JSap0914@users.noreply.github.com>
1 parent a446b39 commit 40e7be8

11 files changed

Lines changed: 35 additions & 0 deletions

File tree

‎PRE_RELEASE_CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@
99
- **HTTP Adapter - native env proxy:** Avoid double-applying environment proxy handling when Node.js native HTTP proxy support is active for the selected agent. Axios still resolves env proxies itself when the selected agent is not using Node's `proxyEnv` support. (**#10942**, closes **#7299**)
1010
- **HTTP Adapter - socketPath:** Path-only request URLs (e.g. `'/foo'`) now work again with `config.socketPath`, fixing the `TypeError [ERR_INVALID_URL]` regression introduced in 1.7.4 when `new URL()` was added to the dispatch path. A synthetic `http://localhost` base is supplied only when an own `socketPath` is set, so absolute URLs, non-socket requests, and prototype-polluted `socketPath` values are unaffected. (**#6611**)
1111

12+
## Documentation
13+
14+
- **Request data defaults:** Clarified that `data` is request-specific and is not inherited or deep-merged from global or instance defaults. Shared body fields should be added with a request interceptor or `transformRequest`, scoped carefully to avoid sending sensitive values to unintended endpoints.
15+
1216
## Release Tracking
1317

1418
- **Proxy Agent Streams:** Guarded Node HTTP adapter TCP keep-alive setup so proxy agents that return generic Duplex streams do not throw when `setKeepAlive` is unavailable. (**#10917**, closes **#10908**)

‎PRE_RELEASE_DOCS.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,16 @@ Do not store raw diffs or line-number-only instructions here; prefer stable sect
2020

2121
## Unreleased
2222

23+
### Request data defaults clarification
24+
25+
- **Change:** Clarify that request `data` is request-specific and is not inherited or deep-merged from defaults.
26+
- **Source:** Documentation clarification for issue #5188 / PR #11020 review.
27+
- **Status:** Applied.
28+
- **Docs targets:** `README.md`; English, Spanish, French, and Chinese request config and config defaults pages.
29+
- **Required content:** Explain that `data` is only taken from the per-request config. Shared body fields should be added with a request interceptor or `transformRequest`, scoped carefully to avoid sending sensitive values to unintended endpoints.
30+
- **Examples:** None required.
31+
- **Notes:** English README/docs and translated docs pages have been updated directly.
32+
2333
### Runtime and type declaration hardening
2434

2535
- **Change:** Document the runtime edge-case fixes and public type declaration additions.

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -776,6 +776,8 @@ These config options are available for requests. Only `url` is required. Request
776776

777777
// `data` is the data to be sent as the request body
778778
// Only applicable for request methods 'PUT', 'POST', 'DELETE', and 'PATCH'
779+
// `data` is request-specific: axios does not inherit or deep-merge it from defaults.
780+
// To add shared body fields, use a request interceptor or transformRequest.
779781
// When no `transformRequest` is set, it must be of one of the following types:
780782
// - string, plain object, ArrayBuffer, ArrayBufferView, URLSearchParams
781783
// - Browser only: FormData, File, Blob
@@ -1199,6 +1201,8 @@ instance.defaults.headers.common['Authorization'] = AUTH_TOKEN;
11991201
12001202
Axios merges config in this order: library defaults from [lib/defaults/index.js](https://github.com/axios/axios/blob/main/lib/defaults/index.js#L49), the instance `defaults` property, and the request `config` argument. Later values take precedence over earlier ones.
12011203
1204+
Some options are request-specific and are only taken from the request `config`. `data` is one of those options: axios does not inherit or deep-merge request bodies from global or instance defaults. If every request needs shared body fields, add them with a request interceptor or `transformRequest`, and scope that logic carefully so sensitive values are not sent to the wrong endpoint.
1205+
12021206
```js
12031207
// Create an instance using the config defaults provided by the library
12041208
// At this point the timeout config value is `0` as is the default for the library

‎docs/es/pages/advanced/config-defaults.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ instance.defaults.headers.common["Authorization"] = AUTH_TOKEN;
3131

3232
La configuración se combinará con un orden de precedencia. El orden es el siguiente: primero se establecen los valores predeterminados de la librería, luego las propiedades predeterminadas de la instancia y, finalmente, el argumento de configuración de la solicitud. A continuación se muestra un ejemplo del orden de precedencia.
3333

34+
Algunas opciones son específicas de cada solicitud y solo se toman de la configuración de la solicitud. `data` es una de ellas: axios no hereda ni fusiona en profundidad cuerpos de solicitud desde los valores predeterminados globales o de instancia. Si todas las solicitudes necesitan campos compartidos en el cuerpo, agrégalos con un interceptor de solicitud o `transformRequest`, y limita cuidadosamente ese comportamiento para no enviar valores sensibles al endpoint equivocado.
35+
3436
Primero, vamos a crear una instancia con los valores predeterminados que proporciona la librería. En este punto, el valor de configuración de timeout es `0`, que es el valor predeterminado de la librería.
3537

3638
```js

‎docs/es/pages/advanced/request-config.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -471,6 +471,8 @@ La propiedad `maxRate` define el **ancho de banda** máximo (en bytes por segund
471471
data: {
472472
firstName: "Fred"
473473
},
474+
// `data` es específico de cada solicitud: axios no lo hereda ni lo fusiona en profundidad desde los valores predeterminados.
475+
// Para agregar campos compartidos al cuerpo, usa un interceptor de solicitud o transformRequest.
474476
formDataHeaderPolicy: "legacy",
475477
// Syntax alternative to send data into the body method post only the value is sent, not the key
476478
data: "Country=Brasil&City=Belo Horizonte",

‎docs/fr/pages/advanced/config-defaults.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ instance.defaults.headers.common["Authorization"] = AUTH_TOKEN;
3131

3232
La configuration est fusionnée selon un ordre de priorité. L'ordre est le suivant : d'abord les valeurs par défaut de la bibliothèque, puis les propriétés par défaut de l'instance, et enfin l'argument de configuration de la requête. Voici un exemple de cet ordre de priorité :
3333

34+
Certaines options sont propres à chaque requête et ne sont lues que depuis la configuration de la requête. `data` en fait partie : axios n'hérite pas des corps de requête depuis les valeurs par défaut globales ou d'instance et ne les fusionne pas en profondeur. Si chaque requête doit inclure des champs de corps communs, ajoutez-les avec un intercepteur de requête ou `transformRequest`, en limitant soigneusement cette logique pour éviter d'envoyer des valeurs sensibles au mauvais point de terminaison.
35+
3436
Créons d'abord une instance avec les valeurs par défaut fournies par la bibliothèque. À ce stade, la valeur de configuration du timeout est `0`, valeur par défaut de la bibliothèque.
3537

3638
```js

‎docs/fr/pages/advanced/request-config.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -471,6 +471,8 @@ La propriété `maxRate` définit la **bande passante** maximale (en octets par
471471
data: {
472472
firstName: "Fred"
473473
},
474+
// `data` est propre à chaque requête : axios ne l'hérite pas et ne le fusionne pas en profondeur depuis les valeurs par défaut.
475+
// Pour ajouter des champs de corps communs, utilisez un intercepteur de requête ou transformRequest.
474476
formDataHeaderPolicy: "legacy",
475477
// Syntaxe alternative pour envoyer des données dans le corps de la méthode post : seule la valeur est envoyée, pas la clé
476478
data: "Country=Brasil&City=Belo Horizonte",

‎docs/pages/advanced/config-defaults.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ instance.defaults.headers.common["Authorization"] = AUTH_TOKEN;
3131

3232
Config will be merged with an order of precedence. The order is as follows, first the library defaults are set, then default properties of the instance, and finally config argument for the request. An example of the order of precedence is shown below:
3333

34+
Some options are request-specific and are only taken from the request config. `data` is one of those options: axios does not inherit or deep-merge request bodies from global or instance defaults. If every request needs shared body fields, add them with a request interceptor or `transformRequest`, and scope that logic carefully so sensitive values are not sent to the wrong endpoint.
35+
3436
First lets create an instance with the defaults provided by the library. At this point the timeout config value is `0` as is the default for the library.
3537

3638
```js

‎docs/pages/advanced/request-config.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -471,6 +471,9 @@ The `maxRate` property defines the maximum **bandwidth** (in bytes per second) f
471471
data: {
472472
firstName: "Fred"
473473
},
474+
475+
// `data` is request-specific: axios does not inherit or deep-merge it from defaults.
476+
// To add shared body fields, use a request interceptor or transformRequest.
474477
formDataHeaderPolicy: "legacy",
475478
// Syntax alternative to send data into the body method post only the value is sent, not the key
476479
data: "Country=Brasil&City=Belo Horizonte",

‎docs/zh/pages/advanced/config-defaults.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ instance.defaults.headers.common["Authorization"] = AUTH_TOKEN;
3131

3232
配置将按照优先级顺序合并，依次为：库的默认值、实例的默认属性，最后是请求时传入的配置参数。下面通过示例说明优先级顺序。
3333

34+
某些选项是请求专属的，只会从请求配置中读取。`data` 就属于这类选项：axios 不会从全局或实例默认值继承请求体，也不会深度合并请求体。如果每个请求都需要共享的请求体字段，请使用请求拦截器或 `transformRequest` 添加，并谨慎限定作用范围，避免把敏感值发送到错误的端点。
35+
3436
首先，创建一个使用库提供的默认值的实例。此时 timeout 配置值为 `0`，这是库的默认值。
3537

3638
```js

0 commit comments

Comments
 (0)