From 45395277baa386d3e55fa2dcf4d78950f297e6b0 Mon Sep 17 00:00:00 2001
From: Ju4tCode <42488585+yanyongyu@users.noreply.github.com>
Date: Wed, 16 Oct 2024 06:16:06 +0000
Subject: [PATCH] :memo: add call rest api directly docs

---
 docs/usage/rest-api.md | 58 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/docs/usage/rest-api.md b/docs/usage/rest-api.md
index 084775b42..9c9c1f7c1 100644
--- a/docs/usage/rest-api.md
+++ b/docs/usage/rest-api.md
@@ -319,3 +319,61 @@ You can also provide a custom map function to handle complex pagination (such as
         accessible_repo: Repository
         print(accessible_repo.full_name)
     ```
+
+## Calling API Directly
+
+In some cases, you may want to call the API directly without using the generated methods. You can use the `github.request` / `github.arequest` method to make a raw request.
+
+For example, to upload a release asset:
+
+=== "Sync"
+
+    ```python hl_lines="11-18"
+    from githubkit import GitHub
+    from githubkit.versions.latest.models import Release, ReleaseAsset
+
+    github = GitHub()
+
+    resp = github.rest.repos.get_release_by_tag(
+        "owner", "repo", "tag_name"
+    )
+    release: Release = resp.parsed_data
+
+    resp = github.request(
+        "POST",
+        release.upload_url.split("{?")[0],  # (1)!
+        params={"name": "test", "label": "description"},
+        content=b"file content",
+        headers={"Content-Type": "application/zip"},
+        response_model=ReleaseAsset,
+    )
+    asset: ReleaseAsset = resp.parsed_data
+    ```
+
+    1. The release `upload_url` is a template URL. In this example, we simply remove the template part.
+
+=== "Async"
+
+    ```python hl_lines="11-18"
+    from githubkit import GitHub
+    from githubkit.versions.latest.models import Release, ReleaseAsset
+
+    github = GitHub()
+
+    resp = await github.rest.repos.async_get_release_by_tag(
+        "owner", "repo", "tag_name"
+    )
+    release: Release = resp.parsed_data
+
+    resp = await github.arequest(
+        "POST",
+        release.upload_url.split("{?")[0],  # (1)!
+        params={"name": "test", "label": "description"},
+        content=b"file content",
+        headers={"Content-Type": "application/zip"},
+        response_model=ReleaseAsset,
+    )
+    asset: ReleaseAsset = resp.parsed_data
+    ```
+
+    1. The release `upload_url` is a template URL. In this example, we simply remove the template part.