From febf8e734148ab94e7ea1808c7873f8ffe2133d2 Mon Sep 17 00:00:00 2001
From: euri10 <euri10@users.noreply.github.com>
Date: Sat, 16 Feb 2019 09:44:56 +0100
Subject: [PATCH] :memo: Add docs for using the Starlette Request directly
 (#25)

Add docs for using the Starlette Request directly
---
 .../src/using_request_directly/tutorial001.py | 10 ++++
 docs/tutorial/extra-starlette.md              |  1 -
 docs/tutorial/using-request-directly.md       | 55 +++++++++++++++++++
 mkdocs.yml                                    |  2 +-
 4 files changed, 66 insertions(+), 2 deletions(-)
 create mode 100644 docs/src/using_request_directly/tutorial001.py
 delete mode 100644 docs/tutorial/extra-starlette.md
 create mode 100644 docs/tutorial/using-request-directly.md

diff --git a/docs/src/using_request_directly/tutorial001.py b/docs/src/using_request_directly/tutorial001.py
new file mode 100644
index 000000000..ca71f32f7
--- /dev/null
+++ b/docs/src/using_request_directly/tutorial001.py
@@ -0,0 +1,10 @@
+from fastapi import FastAPI
+from starlette.requests import Request
+
+app = FastAPI()
+
+
+@app.get("/items/{item_id}")
+def read_root(item_id: str, request: Request):
+    client_host = request.client.host
+    return {"client_host": client_host, "item_id": item_id}
diff --git a/docs/tutorial/extra-starlette.md b/docs/tutorial/extra-starlette.md
deleted file mode 100644
index fdf702fb0..000000000
--- a/docs/tutorial/extra-starlette.md
+++ /dev/null
@@ -1 +0,0 @@
-Coming soon...
\ No newline at end of file
diff --git a/docs/tutorial/using-request-directly.md b/docs/tutorial/using-request-directly.md
new file mode 100644
index 000000000..fe4f93b9c
--- /dev/null
+++ b/docs/tutorial/using-request-directly.md
@@ -0,0 +1,55 @@
+Up to now, you have been declaring the parts of the request that you need with their types.
+
+Taking data from:
+
+* The path as parameters.
+* Headers.
+* Cookies.
+* etc.
+
+And by doing so, **FastAPI** is validating that data, converting it and generating documentation for your API automatically.
+
+But there are situations where you might need to access the `Request` object directly.
+
+## Details about the `Request` object
+
+As **FastAPI** is actually **Starlette** underneath, with a layer of several tools on top, you can use Starlette's <a href="https://www.starlette.io/requests/" target="_blank">`Request`</a> object directly when you need to.
+
+It would also mean that if you get data from the `Request` object directly (for example, read the body) it won't be validated, converted or annotated (with OpenAPI, for the automatic documentation) by FastAPI.
+
+Although any other parameter declared normally (for example, the body with a Pydantic model) would still be validated, converted, annotated, etc.
+
+But there are specific cases where it's useful to get the `Request` object.
+
+## Use the `Request` object direclty
+
+Let's imagine you want to get the client's IP address/host inside of your *path operation function*.
+
+For that you need to access the request directly.
+
+### Import the `Request`
+
+First, import the `Request` class from Starlette:
+
+```Python hl_lines="2"
+{!./src/using_request_directly/tutorial001.py!}
+```
+
+### Declare the `Request` parameter
+
+Then declare a *path operation function* parameter with the type being the `Request` class:
+
+```Python hl_lines="8"
+{!./src/using_request_directly/tutorial001.py!}
+```
+
+!!! tip
+    Note that in this case, we are declaring a path parameter besides the request parameter.
+
+    So, the path parameter will be extracted, validated, converted to the specified type and annotated with OpenAPI.
+
+    The same way, you can declare any other parameter as normally, and additionally, get the `Request` too.
+
+## `Request` documentation
+
+You can read more details about the <a href="https://www.starlette.io/requests/" target="_blank">`Request` object in the official Starlette documentation site</a>.
diff --git a/mkdocs.yml b/mkdocs.yml
index 397a21d9c..ac7abfc50 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -54,12 +54,12 @@ nav:
             - Get Current User: 'tutorial/security/get-current-user.md'
             - Simple OAuth2 with Password and Bearer: 'tutorial/security/simple-oauth2.md'
             - OAuth2 with Password (and hashing), Bearer with JWT tokens: 'tutorial/security/oauth2-jwt.md'
+        - Using the Request Directly: 'tutorial/using-request-directly.md'    
         - SQL (Relational) Databases: 'tutorial/sql-databases.md'
         - NoSQL (Distributed / Big Data) Databases: 'tutorial/nosql-databases.md'
         - Bigger Applications - Multiple Files: 'tutorial/bigger-applications.md'
         - Sub Applications - Behind a Proxy: 'tutorial/sub-applications-proxy.md'
         - Application Configuration: 'tutorial/application-configuration.md'
-        - Extra Starlette options: 'tutorial/extra-starlette.md'    
     - Concurrency and async / await: 'async.md'
     - Deployment: 'deployment.md'
     - Project Generation - Template: 'project-generation.md'