:memo: Add docs for response status codes

diff --git a/docs/img/tutorial/response-status-code/image01.png b/docs/img/tutorial/response-status-code/image01.png
new file mode 100644 (file)
index 0000000..f82803b
Binary files /dev/null and b/docs/img/tutorial/response-status-code/image01.png differ

diff --git a/docs/img/tutorial/response-status-code/image02.png b/docs/img/tutorial/response-status-code/image02.png
new file mode 100644 (file)
index 0000000..9f6327b
Binary files /dev/null and b/docs/img/tutorial/response-status-code/image02.png differ

diff --git a/docs/src/response_status_code/tutorial001.py b/docs/src/response_status_code/tutorial001.py
new file mode 100644 (file)
index 0000000..14b6d6e
--- /dev/null
+++ b/docs/src/response_status_code/tutorial001.py
@@ -0,0 +1,8 @@
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.post("/items/", status_code=201)
+async def create_item(name: str):
+    return {"name": name}

diff --git a/docs/src/response_status_code/tutorial002.py b/docs/src/response_status_code/tutorial002.py
new file mode 100644 (file)
index 0000000..e31a6c1
--- /dev/null
+++ b/docs/src/response_status_code/tutorial002.py
@@ -0,0 +1,9 @@
+from fastapi import FastAPI
+from starlette.status import HTTP_201_CREATED
+
+app = FastAPI()
+
+
+@app.post("/items/", status_code=HTTP_201_CREATED)
+async def create_item(name: str):
+    return {"name": name}

diff --git a/docs/tutorial/response-status-code.md b/docs/tutorial/response-status-code.md
new file mode 100644 (file)
index 0000000..795834c
--- /dev/null
+++ b/docs/tutorial/response-status-code.md
@@ -0,0 +1,71 @@
+The same way you can specify a response model, you can also declare the HTTP status code used for the response with the parameter `status_code` in any of the path operations:
+
+* `@app.get()`
+* `@app.post()`
+* `@app.put()`
+* `@app.delete()`
+* etc.
+
+```Python hl_lines="6"
+{!./src/response_status_code/tutorial001.py!}
+```
+
+!!! note
+    Notice that `status_code` is a parameter of the "decorator" method (`get`, `post`, etc). Not of your path operation function, like all the parameters and body.
+
+The `status_code` parameter receives a number with the HTTP status code.
+
+It will:
+
+* Return that status code in the response.
+* Document it as such in the OpenAPI schema (and so, in the user interfaces):
+
+<img src="/img/tutorial/response-status-code/image01.png">
+
+
+## About HTTP status codes
+
+!!! note
+    If you already know what HTTP status codes are, skip to the next section.
+
+In HTTP, you send a numeric status code of 3 digits as part of the response.
+
+These status codes have a name associated to recognize them, but the important part is the number.
+
+In short:
+
+* `100` and above are for "Information". You rarely use them directly.
+* **`200`** and above are for "Successful" responses. These are the ones you would use the most.
+    * `200` is the default status code, which means everything was "OK".
+    * Another example would be `201`, "Created". It is commonly used after creating a new record in the database.
+* `300` and above are for "Redirection". 
+* **`400`** and above are for "Client error" responses. These are the second type you would probably use the most.
+    * An example is `404`, for a "Not Found" response.
+    * For generic errors from the client, you can just use `400`.
+* `500` and above are for server errors. You almost never use them directly. When something goes wrong at some part in your application code, or server, it will automatically return one of these status codes.
+
+!!! tip
+    To know more about each status code and which code is for what, check the <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status" target="_blank"><abbr title="Mozilla Developer Network">MDN</abbr> documentation about HTTP status codes</a>.
+
+
+## Shortcut to remember the names
+
+Let's see the previous example again:
+
+```Python hl_lines="6"
+{!./src/response_status_code/tutorial001.py!}
+```
+
+`201` is the status code for "Created".
+
+But you don't have to memorize what each of these codes mean.
+
+You can use the convenience variables from `starlette.status`.
+
+```Python hl_lines="2 7"
+{!./src/response_status_code/tutorial002.py!}
+```
+
+They are just a convenience, they hold the same number, but that way you can use the editor's autocomplete to find them:
+
+<img src="/img/tutorial/response-status-code/image02.png">

diff --git a/mkdocs.yml b/mkdocs.yml
index 6fe4d9763d084fa9552c54a99442877dfd8e6623..c687756a4e0cb37240dccc69023b94320e9f77a8 100644 (file)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -33,6 +33,7 @@ nav:
         - Header Parameters: 'tutorial/header-params.md'
         - Response Model: 'tutorial/response-model.md'
         - Extra Models: 'tutorial/extra-models.md'
+        - Response Status Code: 'tutorial/response-status-code.md'
         - Form Data: 'tutorial/request-forms.md'
         - Request Files: 'tutorial/request-files.md'
         - Request Forms and Files: 'tutorial/request-forms-and-files.md'