Skip to content

Commit 2101c2c

Browse files
docs(api): clarify JSON string request bodies (#43945)
Co-authored-by: microsoft-playwright-automation[bot] <203992400+microsoft-playwright-automation[bot]@users.noreply.github.com>
1 parent fae3b10 commit 2101c2c

5 files changed

Lines changed: 188 additions & 51 deletions

File tree

‎docs/src/api/class-apirequestcontext.md‎

Lines changed: 28 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -272,7 +272,10 @@ context cookies from the response. The method will automatically follow redirect
272272
### option: APIRequestContext.delete.headers = %%-js-python-csharp-fetch-option-headers-%%
273273
* since: v1.16
274274

275-
### option: APIRequestContext.delete.data = %%-js-python-csharp-fetch-option-data-%%
275+
### option: APIRequestContext.delete.data = %%-js-fetch-option-data-%%
276+
* since: v1.17
277+
278+
### option: APIRequestContext.delete.data = %%-python-csharp-fetch-option-data-%%
276279
* since: v1.17
277280

278281
### option: APIRequestContext.delete.form = %%-js-fetch-option-form-%%
@@ -451,7 +454,10 @@ If set changes the fetch method (e.g. [PUT](https://developer.mozilla.org/en-US/
451454
### option: APIRequestContext.fetch.headers = %%-js-python-csharp-fetch-option-headers-%%
452455
* since: v1.16
453456

454-
### option: APIRequestContext.fetch.data = %%-js-python-csharp-fetch-option-data-%%
457+
### option: APIRequestContext.fetch.data = %%-js-fetch-option-data-%%
458+
* since: v1.16
459+
460+
### option: APIRequestContext.fetch.data = %%-python-csharp-fetch-option-data-%%
455461
* since: v1.16
456462

457463
### option: APIRequestContext.fetch.form = %%-js-fetch-option-form-%%
@@ -566,7 +572,10 @@ await request.GetAsync("https://example.com/api/getText", new() { Params = query
566572
### option: APIRequestContext.get.headers = %%-js-python-csharp-fetch-option-headers-%%
567573
* since: v1.16
568574

569-
### option: APIRequestContext.get.data = %%-js-python-csharp-fetch-option-data-%%
575+
### option: APIRequestContext.get.data = %%-js-fetch-option-data-%%
576+
* since: v1.26
577+
578+
### option: APIRequestContext.get.data = %%-python-csharp-fetch-option-data-%%
570579
* since: v1.26
571580

572581
### option: APIRequestContext.get.form = %%-js-fetch-option-form-%%
@@ -633,7 +642,10 @@ context cookies from the response. The method will automatically follow redirect
633642
### option: APIRequestContext.head.headers = %%-js-python-csharp-fetch-option-headers-%%
634643
* since: v1.16
635644

636-
### option: APIRequestContext.head.data = %%-js-python-csharp-fetch-option-data-%%
645+
### option: APIRequestContext.head.data = %%-js-fetch-option-data-%%
646+
* since: v1.26
647+
648+
### option: APIRequestContext.head.data = %%-python-csharp-fetch-option-data-%%
637649
* since: v1.26
638650

639651
### option: APIRequestContext.head.form = %%-python-fetch-option-form-%%
@@ -700,7 +712,10 @@ context cookies from the response. The method will automatically follow redirect
700712
### option: APIRequestContext.patch.headers = %%-js-python-csharp-fetch-option-headers-%%
701713
* since: v1.16
702714

703-
### option: APIRequestContext.patch.data = %%-js-python-csharp-fetch-option-data-%%
715+
### option: APIRequestContext.patch.data = %%-js-fetch-option-data-%%
716+
* since: v1.16
717+
718+
### option: APIRequestContext.patch.data = %%-python-csharp-fetch-option-data-%%
704719
* since: v1.16
705720

706721
### option: APIRequestContext.patch.form = %%-js-fetch-option-form-%%
@@ -888,7 +903,10 @@ await request.PostAsync("https://example.com/api/uploadScript", new() { Multipar
888903
### option: APIRequestContext.post.headers = %%-js-python-csharp-fetch-option-headers-%%
889904
* since: v1.16
890905

891-
### option: APIRequestContext.post.data = %%-js-python-csharp-fetch-option-data-%%
906+
### option: APIRequestContext.post.data = %%-js-fetch-option-data-%%
907+
* since: v1.16
908+
909+
### option: APIRequestContext.post.data = %%-python-csharp-fetch-option-data-%%
892910
* since: v1.16
893911

894912
### option: APIRequestContext.post.form = %%-js-fetch-option-form-%%
@@ -955,7 +973,10 @@ context cookies from the response. The method will automatically follow redirect
955973
### option: APIRequestContext.put.headers = %%-js-python-csharp-fetch-option-headers-%%
956974
* since: v1.16
957975

958-
### option: APIRequestContext.put.data = %%-js-python-csharp-fetch-option-data-%%
976+
### option: APIRequestContext.put.data = %%-js-fetch-option-data-%%
977+
* since: v1.16
978+
979+
### option: APIRequestContext.put.data = %%-python-csharp-fetch-option-data-%%
959980
* since: v1.16
960981

961982
### option: APIRequestContext.put.form = %%-python-fetch-option-form-%%

‎docs/src/api/params.md‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -579,8 +579,24 @@ unless explicitly provided. File values can be passed as file-like object contai
579579

580580
An instance of [FormData] can be created via [`method: APIRequestContext.createFormData`].
581581

582-
## js-python-csharp-fetch-option-data
583-
* langs: js, python, csharp
582+
## js-fetch-option-data
583+
* langs: js
584+
- `data` <[string]|[Buffer]|[Serializable]>
585+
586+
Allows to set post data of the request. If the data parameter is an object other than a [Buffer], it will be serialized to JSON
587+
and the `content-type` header will be set to `application/json` if not explicitly set.
588+
589+
If the data parameter is a string and the explicitly set `content-type` is `application/json` (case-insensitive,
590+
with optional parameters such as `charset=utf-8`), the string is sent as is if it parses as JSON.
591+
Otherwise, it is JSON-encoded as a string, including quotes and escaping. Strings with other content types
592+
are sent as is.
593+
594+
Pass a [Buffer], such as `Buffer.from(body, 'utf8')`, to send exact bytes without JSON encoding,
595+
for example to send deliberately malformed JSON or a body used to compute a signature.
596+
For strings and buffers, the `content-type` header defaults to `application/octet-stream` if not explicitly set.
597+
598+
## python-csharp-fetch-option-data
599+
* langs: python, csharp
584600
- `data` <[string]|[Buffer]|[Serializable]>
585601

586602
Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string

‎docs/src/release-notes-js.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,8 @@ export default defineConfig({
9292

9393
- String and `URLSearchParams` values of the `params` option in [APIRequestContext] requests are now appended to the query that the URL already has, instead of replacing it.
9494

95+
- [APIRequestContext] now matches `application/json` content types case-insensitively and with parameters, such as `application/json;charset=UTF-8`, when serializing string `data`. Previously, only the exact value `application/json` triggered JSON encoding. With these content types, a string that does not parse as JSON is now JSON-encoded, including quotes and escaping, instead of being sent as is. This changes malformed JSON bodies and can invalidate signatures computed over the original string. Pass `data: Buffer.from(body, 'utf8')` to send exact bytes without JSON encoding. Strings that already parse as JSON and `Buffer` data are unchanged.
96+
9597
- `.css`, `.less` and `.scss` imports in test files now load as empty modules instead of being removed, so the imported file must exist.
9698

9799
- The blob reporter again deletes the content of its output directory before it writes the report. Playwright 1.64 kept reports with other names.

‎packages/playwright-client/types/types.d.ts‎

Lines changed: 70 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -19907,9 +19907,16 @@ export interface APIRequestContext {
1990719907
*/
1990819908
delete<T = any>(url: string, options?: {
1990919909
/**
19910-
* Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string
19911-
* and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type`
19912-
* header will be set to `application/octet-stream` if not explicitly set.
19910+
* Allows to set post data of the request. If the data parameter is an object other than a [Buffer], it will be
19911+
* serialized to JSON and the `content-type` header will be set to `application/json` if not explicitly set.
19912+
*
19913+
* If the data parameter is a string and the explicitly set `content-type` is `application/json` (case-insensitive,
19914+
* with optional parameters such as `charset=utf-8`), the string is sent as is if it parses as JSON. Otherwise, it is
19915+
* JSON-encoded as a string, including quotes and escaping. Strings with other content types are sent as is.
19916+
*
19917+
* Pass a [Buffer], such as `Buffer.from(body, 'utf8')`, to send exact bytes without JSON encoding, for example to
19918+
* send deliberately malformed JSON or a body used to compute a signature. For strings and buffers, the `content-type`
19919+
* header defaults to `application/octet-stream` if not explicitly set.
1991319920
*/
1991419921
data?: string|Buffer|Serializable;
1991519922

@@ -20049,9 +20056,16 @@ export interface APIRequestContext {
2004920056
*/
2005020057
fetch<T = any>(urlOrRequest: string|Request, options?: {
2005120058
/**
20052-
* Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string
20053-
* and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type`
20054-
* header will be set to `application/octet-stream` if not explicitly set.
20059+
* Allows to set post data of the request. If the data parameter is an object other than a [Buffer], it will be
20060+
* serialized to JSON and the `content-type` header will be set to `application/json` if not explicitly set.
20061+
*
20062+
* If the data parameter is a string and the explicitly set `content-type` is `application/json` (case-insensitive,
20063+
* with optional parameters such as `charset=utf-8`), the string is sent as is if it parses as JSON. Otherwise, it is
20064+
* JSON-encoded as a string, including quotes and escaping. Strings with other content types are sent as is.
20065+
*
20066+
* Pass a [Buffer], such as `Buffer.from(body, 'utf8')`, to send exact bytes without JSON encoding, for example to
20067+
* send deliberately malformed JSON or a body used to compute a signature. For strings and buffers, the `content-type`
20068+
* header defaults to `application/octet-stream` if not explicitly set.
2005520069
*/
2005620070
data?: string|Buffer|Serializable;
2005720071

@@ -20178,9 +20192,16 @@ export interface APIRequestContext {
2017820192
*/
2017920193
get<T = any>(url: string, options?: {
2018020194
/**
20181-
* Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string
20182-
* and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type`
20183-
* header will be set to `application/octet-stream` if not explicitly set.
20195+
* Allows to set post data of the request. If the data parameter is an object other than a [Buffer], it will be
20196+
* serialized to JSON and the `content-type` header will be set to `application/json` if not explicitly set.
20197+
*
20198+
* If the data parameter is a string and the explicitly set `content-type` is `application/json` (case-insensitive,
20199+
* with optional parameters such as `charset=utf-8`), the string is sent as is if it parses as JSON. Otherwise, it is
20200+
* JSON-encoded as a string, including quotes and escaping. Strings with other content types are sent as is.
20201+
*
20202+
* Pass a [Buffer], such as `Buffer.from(body, 'utf8')`, to send exact bytes without JSON encoding, for example to
20203+
* send deliberately malformed JSON or a body used to compute a signature. For strings and buffers, the `content-type`
20204+
* header defaults to `application/octet-stream` if not explicitly set.
2018420205
*/
2018520206
data?: string|Buffer|Serializable;
2018620207

@@ -20275,9 +20296,16 @@ export interface APIRequestContext {
2027520296
*/
2027620297
head<T = any>(url: string, options?: {
2027720298
/**
20278-
* Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string
20279-
* and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type`
20280-
* header will be set to `application/octet-stream` if not explicitly set.
20299+
* Allows to set post data of the request. If the data parameter is an object other than a [Buffer], it will be
20300+
* serialized to JSON and the `content-type` header will be set to `application/json` if not explicitly set.
20301+
*
20302+
* If the data parameter is a string and the explicitly set `content-type` is `application/json` (case-insensitive,
20303+
* with optional parameters such as `charset=utf-8`), the string is sent as is if it parses as JSON. Otherwise, it is
20304+
* JSON-encoded as a string, including quotes and escaping. Strings with other content types are sent as is.
20305+
*
20306+
* Pass a [Buffer], such as `Buffer.from(body, 'utf8')`, to send exact bytes without JSON encoding, for example to
20307+
* send deliberately malformed JSON or a body used to compute a signature. For strings and buffers, the `content-type`
20308+
* header defaults to `application/octet-stream` if not explicitly set.
2028120309
*/
2028220310
data?: string|Buffer|Serializable;
2028320311

@@ -20372,9 +20400,16 @@ export interface APIRequestContext {
2037220400
*/
2037320401
patch<T = any>(url: string, options?: {
2037420402
/**
20375-
* Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string
20376-
* and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type`
20377-
* header will be set to `application/octet-stream` if not explicitly set.
20403+
* Allows to set post data of the request. If the data parameter is an object other than a [Buffer], it will be
20404+
* serialized to JSON and the `content-type` header will be set to `application/json` if not explicitly set.
20405+
*
20406+
* If the data parameter is a string and the explicitly set `content-type` is `application/json` (case-insensitive,
20407+
* with optional parameters such as `charset=utf-8`), the string is sent as is if it parses as JSON. Otherwise, it is
20408+
* JSON-encoded as a string, including quotes and escaping. Strings with other content types are sent as is.
20409+
*
20410+
* Pass a [Buffer], such as `Buffer.from(body, 'utf8')`, to send exact bytes without JSON encoding, for example to
20411+
* send deliberately malformed JSON or a body used to compute a signature. For strings and buffers, the `content-type`
20412+
* header defaults to `application/octet-stream` if not explicitly set.
2037820413
*/
2037920414
data?: string|Buffer|Serializable;
2038020415

@@ -20511,9 +20546,16 @@ export interface APIRequestContext {
2051120546
*/
2051220547
post<T = any>(url: string, options?: {
2051320548
/**
20514-
* Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string
20515-
* and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type`
20516-
* header will be set to `application/octet-stream` if not explicitly set.
20549+
* Allows to set post data of the request. If the data parameter is an object other than a [Buffer], it will be
20550+
* serialized to JSON and the `content-type` header will be set to `application/json` if not explicitly set.
20551+
*
20552+
* If the data parameter is a string and the explicitly set `content-type` is `application/json` (case-insensitive,
20553+
* with optional parameters such as `charset=utf-8`), the string is sent as is if it parses as JSON. Otherwise, it is
20554+
* JSON-encoded as a string, including quotes and escaping. Strings with other content types are sent as is.
20555+
*
20556+
* Pass a [Buffer], such as `Buffer.from(body, 'utf8')`, to send exact bytes without JSON encoding, for example to
20557+
* send deliberately malformed JSON or a body used to compute a signature. For strings and buffers, the `content-type`
20558+
* header defaults to `application/octet-stream` if not explicitly set.
2051720559
*/
2051820560
data?: string|Buffer|Serializable;
2051920561

@@ -20608,9 +20650,16 @@ export interface APIRequestContext {
2060820650
*/
2060920651
put<T = any>(url: string, options?: {
2061020652
/**
20611-
* Allows to set post data of the request. If the data parameter is an object, it will be serialized to json string
20612-
* and `content-type` header will be set to `application/json` if not explicitly set. Otherwise the `content-type`
20613-
* header will be set to `application/octet-stream` if not explicitly set.
20653+
* Allows to set post data of the request. If the data parameter is an object other than a [Buffer], it will be
20654+
* serialized to JSON and the `content-type` header will be set to `application/json` if not explicitly set.
20655+
*
20656+
* If the data parameter is a string and the explicitly set `content-type` is `application/json` (case-insensitive,
20657+
* with optional parameters such as `charset=utf-8`), the string is sent as is if it parses as JSON. Otherwise, it is
20658+
* JSON-encoded as a string, including quotes and escaping. Strings with other content types are sent as is.
20659+
*
20660+
* Pass a [Buffer], such as `Buffer.from(body, 'utf8')`, to send exact bytes without JSON encoding, for example to
20661+
* send deliberately malformed JSON or a body used to compute a signature. For strings and buffers, the `content-type`
20662+
* header defaults to `application/octet-stream` if not explicitly set.
2061420663
*/
2061520664
data?: string|Buffer|Serializable;
2061620665

0 commit comments

Comments
 (0)