diff --git a/docs/tutorial/first-steps.md b/docs/tutorial/first-steps.md index 40c4d1ba3..5b41bfc4a 100644 --- a/docs/tutorial/first-steps.md +++ b/docs/tutorial/first-steps.md @@ -148,7 +148,7 @@ https://example.com/items/foo !!! info A "path" is also commonly called an "endpoint" or a "route". -Building an API, the "path" is the main way to separate "concerns" and functionalities. +Building an API, the "path" is the main way to separate "concerns" and "resources". #### Operation @@ -172,7 +172,7 @@ In the HTTP protocol, you can communicate to each path using one (or more) of th --- -When building APIs, you normally use these specific HTTP methods to perform a specific operation. +When building APIs, you normally use these specific HTTP methods to perform a specific action. Normally you use: @@ -183,7 +183,7 @@ Normally you use: So, in OpenAPI, each of the HTTP methods is called an "operation". -We are going to call them "operations" too. +We are going to call them "**operations**" too. #### Define a path operation function @@ -196,6 +196,17 @@ The `@app.get("/")` tells **FastAPI** that the function right below is in charge * the path `/` * using a get operation +!!! info "`@decorator` Info" + That `@something` syntax in Python is called a "decorator". + + You put it on top of a function. Like a pretty decorative hat (I guess that's where the term came from). + + A "decorator" takes the function below and does something with it. + + In our case, this decorator tells **FastAPI** that the function below corresponds to the **path** `/` with an **operation** `get`. + + It is the "**path operation decorator**". + You can also use the other operations: * `@app.post()` @@ -216,9 +227,15 @@ And the more exotic ones: The information here is presented as a guideline, not a requirement. - For example, when using GraphQL you normally perform all the operations using only `post`. + For example, when using GraphQL you normally perform all the actions using only `post`. + +### Step 4: define the **path operation function** -### Step 4: define the path operation function +This is our "**path operation function**": + +* **path**: is `/`. +* **operation**: is `get`. +* **function**: is the function below the "decorator" (below `@app.get("/")`). ```Python hl_lines="7" {!./src/first_steps/tutorial001.py!} @@ -226,7 +243,7 @@ And the more exotic ones: This is a Python function. -It will be called by FastAPI whenever it receives a request to the URL "`/`". +It will be called by **FastAPI** whenever it receives a request to the URL "`/`" using `GET`. In this case, it is an `async` function. @@ -238,7 +255,8 @@ You could also define it as a normal function instead of `async def`: {!./src/first_steps/tutorial003.py!} ``` -To know the difference, read the section about [Concurrency and `async` / `await`](/async/). +!!! note + If you don't know the difference, check the _"In a hurry?"_ section about `async` and `await` in the docs. ### Step 5: return the content @@ -250,4 +268,13 @@ You can return a `dict`, `list`, singular values as `str`, `int`, etc. You can also return Pydantic models (you'll see more about that later). -There are many other objects and models that will be automatically converted to JSON. +There are many other objects and models that will be automatically converted to JSON (including ORMs, etc). Try using your favorite ones, it's highly probable that they are already supported. + + +## Recap + +* Import `FastAPI`. +* Create an `app` instance. +* Write a **path operation decorator** (like `@app.get("/")`). +* Write a **path operation function** (like `def root(): ...` above). +* Run the debugging server (like `uvicorn main:app --debug`). \ No newline at end of file