docs(python): add request API examples (microsoft#10512)

Author: mxschmitt

docs/src/api/class-apirequest.md

@@ -1,7 +1,10 @@
 # class: APIRequest
 * langs: js, java, python
 
-Exposes API that can be used for the Web API testing.
+Exposes API that can be used for the Web API testing. Each Playwright browser context
+has a APIRequestContext instance attached which shares cookies with the page context.
+Its also possible to create a new APIRequestContext instance manually. For more information
+see [here](./class-apirequestcontext).
 
 ## async method: APIRequest.newContext
 * langs: js, java, python

docs/src/api/class-apirequestcontext.md

@@ -6,6 +6,106 @@ environment or the service to your e2e test. When used on [Page] or a [BrowserCo
 the cookies from the corresponding [BrowserContext]. This means that if you log in using this API, your e2e test
 will be logged in and vice versa.
 
+```python async
+import os
+import asyncio
+from playwright.async_api import async_playwright, Playwright
+
+REPO = "test-repo-1"
+USER = "github-username"
+API_TOKEN = os.getenv("GITHUB_API_TOKEN")
+
+async def run(playwright: Playwright):
+    # This will launch a new browser, create a context and page. When making HTTP
+    # requests with the internal APIRequestContext (e.g. `context.request` or `page.request`)
+    # it will automatically set the cookies to the browser page and vise versa.
+    browser = await playwright.chromium.launch()
+    context = await browser.new_context(base_url="https://api.github.com")
+    api_request_context = context.request
+    page = await context.new_page()
+
+    # Alternatively you can create a APIRequestContext manually without having a browser context attached:
+    # api_request_context = await playwright.request.new_context(base_url="https://api.github.com")
+
+    # Create a repository.
+    response = await api_request_context.post(
+        "/user/repos",
+        headers={
+            "Accept": "application/vnd.github.v3+json",
+            # Add GitHub personal access token.
+            "Authorization": f"token {API_TOKEN}",
+        },
+        data={"name": REPO},
+    )
+    assert response.ok
+    assert response.json()["name"] == REPO
+
+    # Delete a repository.
+    response = await api_request_context.delete(
+        f"/repos/{USER}/{REPO}",
+        headers={
+            "Accept": "application/vnd.github.v3+json",
+            # Add GitHub personal access token.
+            "Authorization": f"token {API_TOKEN}",
+        },
+    )
+    assert response.ok
+    assert await response.body() == '{"status": "ok"}'
+
+async def main():
+    async with async_playwright() as playwright:
+        await run(playwright)
+
+asyncio.run(main())
+```
+
+```python sync
+import os
+from playwright.sync_api import sync_playwright
+
+REPO = "test-repo-1"
+USER = "github-username"
+API_TOKEN = os.getenv("GITHUB_API_TOKEN")
+
+with sync_playwright() as p:
+    # This will launch a new browser, create a context and page. When making HTTP
+    # requests with the internal APIRequestContext (e.g. `context.request` or `page.request`)
+    # it will automatically set the cookies to the browser page and vise versa.
+    browser = playwright.chromium.launch()
+    context = browser.new_context(base_url="https://api.github.com")
+    api_request_context = context.request
+    page = context.new_page()
+
+    # Alternatively you can create a APIRequestContext manually without having a browser context attached:
+    # api_request_context = playwright.request.new_context(base_url="https://api.github.com")
+
+
+    # Create a repository.
+    response = api_request_context.post(
+        "/user/repos",
+        headers={
+            "Accept": "application/vnd.github.v3+json",
+            # Add GitHub personal access token.
+            "Authorization": f"token {API_TOKEN}",
+        },
+        data={"name": REPO},
+    )
+    assert response.ok
+    assert response.json()["name"] == REPO
+
+    # Delete a repository.
+    response = api_request_context.delete(
+        f"/repos/{USER}/{REPO}",
+        headers={
+            "Accept": "application/vnd.github.v3+json",
+            # Add GitHub personal access token.
+            "Authorization": f"token {API_TOKEN}",
+        },
+    )
+    assert response.ok
+    assert await response.body() == '{"status": "ok"}'
+```
+
 ## async method: APIRequestContext.delete
 - returns: <[APIResponse]>
 

docs/src/api/class-apiresponse.md

@@ -3,6 +3,40 @@
 
 [APIResponse] class represents responses returned by [`method: APIRequestContext.get`] and similar methods.
 
+```python async
+import asyncio
+from playwright.async_api import async_playwright, Playwright
+
+async def run(playwright: Playwright):
+    context = await playwright.request.new_context()
+    response = await context.get("https://example.com/user/repos")
+    assert response.ok
+    assert response.status == 200
+    assert response.headers["content-type"] == "application/json; charset=utf-8"
+    assert response.json()["name"] == "foobar"
+    assert await response.body() == '{"status": "ok"}'
+
+
+async def main():
+    async with async_playwright() as playwright:
+        await run(playwright)
+
+asyncio.run(main())
+```
+
+```python sync
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    context = playwright.request.new_context()
+    response = context.get("https://example.com/user/repos")
+    assert response.ok
+    assert response.status == 200
+    assert response.headers["content-type"] == "application/json; charset=utf-8"
+    assert response.json()["name"] == "foobar"
+    assert response.body() == '{"status": "ok"}'
+```
+
 ## async method: APIResponse.body
 - returns: <[Buffer]>
 

docs/src/test-api-testing-js.md

@@ -163,7 +163,7 @@ const USER = 'github-username';
   });
 
   // Delete a repository.
-  await context.delete(`/repos/${USER}/${REPO}`{
+  await context.delete(`/repos/${USER}/${REPO}`, {
     headers: {
       'Accept': 'application/vnd.github.v3+json',
       // Add GitHub personal access token.

packages/playwright-core/types/types.d.ts

@@ -11813,7 +11813,9 @@ export interface AndroidWebView {
 }
 
 /**
- * Exposes API that can be used for the Web API testing.
+ * Exposes API that can be used for the Web API testing. Each Playwright browser context has a APIRequestContext instance
+ * attached which shares cookies with the page context. Its also possible to create a new APIRequestContext instance
+ * manually. For more information see [here](https://playwright.dev/docs/class-apirequestcontext).
  */
 export interface APIRequest {
   /**
@@ -11939,6 +11941,7 @@ export interface APIRequest {
  * environment or the service to your e2e test. When used on [Page] or a [BrowserContext], this API will automatically use
  * the cookies from the corresponding [BrowserContext]. This means that if you log in using this API, your e2e test will be
  * logged in and vice versa.
+ *
  */
 export interface APIRequestContext {
   /**
@@ -12428,6 +12431,7 @@ export interface APIRequestContext {
  * [APIResponse] class represents responses returned by
  * [apiRequestContext.get(url[, options])](https://playwright.dev/docs/api/class-apirequestcontext#api-request-context-get)
  * and similar methods.
+ *
  */
 export interface APIResponse {
   /**