📝 Update docs, use the term path operation

docs/tutorial/body-multiple-params.md

@@ -14,7 +14,7 @@ First, of course, you can mix `Path`, `Query` and request body parameter declara
 
 ## Multiple body parameters
 
-In the previous example, the endpoint would expect a JSON body with the attributes of an `Item`, like:
+In the previous example, the path operations would expect a JSON body with the attributes of an `Item`, like:
 
 ```JSON
 {
@@ -158,9 +158,9 @@ instead of:
 
 ## Recap
 
-You can add multiple body parameters to your function endpoint, even though a request can only have a single body.
+You can add multiple body parameters to your path operation function, even though a request can only have a single body.
 
-But **FastAPI** will handle it, give you the correct data in your function, and validate and document the correct schema in the endpoint.
+But **FastAPI** will handle it, give you the correct data in your function, and validate and document the correct schema in the path operation.
 
 You can also declare singular values to be received as part of the body.
 

docs/tutorial/body-schema.md

@@ -1,4 +1,4 @@
-The same way you can declare additional validation and metadata in endpoint function parameters with `Query`, `Path` and `Body`, you can declare validation and metadata inside of Pydantic models using `Schema`.
+The same way you can declare additional validation and metadata in path operation function parameters with `Query`, `Path` and `Body`, you can declare validation and metadata inside of Pydantic models using `Schema`.
 
 ## Import Schema
 
@@ -29,7 +29,7 @@ You can then use `Schema` with model attributes:
     `Body` is also a subclass of `Schema` directly. And there are others you will see later that are subclasses of `Body`.
 
 !!! tip
-    Notice how each model's attribute with a type, default value and `Schema` has the same structure as an endpoint's function's parameter, with `Schema` instead of `Path`, `Query` and `Body`.
+    Notice how each model's attribute with a type, default value and `Schema` has the same structure as a path operation function's parameter, with `Schema` instead of `Path`, `Query` and `Body`.
 
 ## Schema extras
 

docs/tutorial/body.md

@@ -42,7 +42,7 @@ For example, this model above declares a JSON "`object`" (or Python `dict`) like
 
 ## Declare it as a parameter
 
-To add it to your endpoint, declare it the same way you declared path and query parameters:
+To add it to your path operation, declare it the same way you declared path and query parameters:
 
 ```Python hl_lines="16"
 {!./tutorial/src/body/tutorial001.py!}
@@ -69,7 +69,7 @@ The JSON Schemas of your models will be part of your OpenAPI generated schema, a
 
 <img src="/img/tutorial/body/image01.png">
 
-And will be also used in the API docs inside each endpoint that needs them:
+And will be also used in the API docs inside each path operation that needs them:
 
 <img src="/img/tutorial/body/image02.png">
 

docs/tutorial/first-steps.md

@@ -94,6 +94,11 @@ It will show a JSON starting with something like:
 
 `FastAPI` is a Python class that provides all the functionality for your API.
 
+!!! note "Technical Details"
+    `FastAPI` is a class that inherits directly from `Starlette`.
+
+    You can use all the Starlette functionality with `FastAPI` too.
+
 ### Step 2: create a `FastAPI` "instance"
 
 ```Python hl_lines="3"
@@ -102,7 +107,7 @@ It will show a JSON starting with something like:
 
 Here the `app` variable will be an "instance" of the class `FastAPI`.
 
-This will be the main point of interaction to create all your API endpoints.
+This will be the main point of interaction to create all your API.
 
 This `app` is the same one referred by `uvicorn` in thet command:
 
@@ -122,28 +127,98 @@ And put it in a file `main.py`, then you would call `uvicorn` like:
 uvicorn main:my_awesome_api --debug
 ```
 
-### Step 3: create an endpoint
+### Step 3: create a path operation
+
+#### Path
+
+"Path" here refers to the last part of the URL starting from the first `/`.
+
+So, in a URL like:
+
+```
+https://example.com/items/foo
+```
+
+...the path would be:
+
+```
+/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.
+
+#### Operation
+
+"Operation" here refers to one of the HTTP "methods".
+
+One of:
+
+* `POST`
+* `GET`
+* `PUT`
+* `DELETE`
+
+...and the more exotic ones:
+
+* `OPTIONS`
+* `HEAD`
+* `PATCH`
+* `TRACE`
+
+In the HTTP protocol, you can communicate to each path using one (or more) of these "methods".
+
+---
+
+When building APIs, you normally use these specific HTTP methods to perform a specific operation.
+
+Normally you use:
+
+* `POST`: to create data.
+* `GET`: to read data.
+* `PUT`: to update data.
+* `DELETE`: to delete data.
+
+So, in OpenAPI, each of the HTTP methods is called an "operation".
+
+We are going to call them "operations" too.
+
+#### Define a path operation function
 
 ```Python hl_lines="6"
 {!tutorial/src/first-steps/tutorial001.py!}
 ```
 
-The `@app.get("/")` tells **FastAPI** that the function right below is an endpoint and that it should go to the path route `/`.
+The `@app.get("/")` tells **FastAPI** that the function right below is in charge of handling requests that go to:
 
-You can also use other HTTP methods:
+* the path `/`
+* using a <abbr title="an HTTP GET method"><code>get</code> operation</abbr>
+
+You can also use the other operations:
 
 * `@app.post()`
 * `@app.put()`
 * `@app.delete()`
 
-And more exotic ones:
+And the more exotic ones:
 
 * `@app.options()`
 * `@app.head()`
 * `@app.patch()`
 * `@app.trace()`
 
-### Step 4: define the endpoint function
+!!! tip
+    You are free to use each operation (HTTP method) as you wish.
+    
+    **FastAPI** doesn't enforce any specific meaning.
+
+    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`.
+
+### Step 4: define the path operation function
 
 ```Python hl_lines="7"
 {!tutorial/src/first-steps/tutorial001.py!}

docs/tutorial/query-params-str-validations.md

@@ -51,7 +51,7 @@ And then, we can pass more parameters to `Query`. In this case, the `max_length`
 q: str = Query(None, max_length=50)
 ```
 
-This will validate the data, show a clear error when the data is not valid, and document the parameter in the OpenAPI schema endpoint.
+This will validate the data, show a clear error when the data is not valid, and document the parameter in the OpenAPI schema path operation.
 
 
 ## Add more validations

docs/tutorial/request-files.md

@@ -39,7 +39,7 @@ The way HTML forms (`<form></form>`) sends the data to the server normally uses
 
 
 !!! warning
-    You can declare multiple `File` and `Form` parameters in an endpoint, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `multipart/form-data` instead of `application/json`.
+    You can declare multiple `File` and `Form` parameters in a path operation, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `multipart/form-data` instead of `application/json`.
 
     This is not a limitation of **FastAPI**, it's part of the HTTP protocol.
 

docs/tutorial/request-forms-and-files.md

@@ -17,7 +17,7 @@ Create file and form parameters the same way you would for `Body` or `Query`:
 The files and form fields will be uploaded as form data and you will receive the files and form fields.
 
 !!! warning
-    You can declare multiple `File` and `Form` parameters in an endpoint, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `multipart/form-data` instead of `application/json`.
+    You can declare multiple `File` and `Form` parameters in a path operation, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `multipart/form-data` instead of `application/json`.
 
     This is not a limitation of **FastAPI**, it's part of the HTTP protocol.
 

docs/tutorial/request-forms.md

@@ -43,7 +43,7 @@ The way HTML forms (`<form></form>`) sends the data to the server normally uses
 
 
 !!! warning
-    You can declare multiple `Form` parameters in an endpoint, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `application/x-www-form-urlencoded` instead of `application/json`.
+    You can declare multiple `Form` parameters in a path operation, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `application/x-www-form-urlencoded` instead of `application/json`.
 
     This is not a limitation of **FastAPI**, it's part of the HTTP protocol.
 

docs/tutorial/response-model.md

@@ -1,4 +1,4 @@
-You can declare the model used for the response with the parameter `response_model` in any of the endpoint creation methods:
+You can declare the model used for the response with the parameter `response_model` in any of the path operations:
 
 * `@app.get()`
 * `@app.post()`
@@ -11,13 +11,13 @@ You can declare the model used for the response with the parameter `response_mod
 ```
 
 !!! note
-    Notice that `response_model` is a parameter of the "decorator" method (`get`, `post`, etc), not of your endpoint function like all the parameters and body.
+    Notice that `response_model` is a parameter of the "decorator" method (`get`, `post`, etc). Not of your path operation function, like all the parameters and body.
 
 It receives a standard Pydantic model and will:
 
 * Convert the output data to the type declarations of the model
 * Validate the data
-* Add a JSON Schema for the response, in the OpenAPI endpoint
+* Add a JSON Schema for the response, in the OpenAPI path operation
 * Will be used by the automatic documentation systems
 
 But most importantly:
@@ -42,7 +42,7 @@ Now, whenever a browser is creating a user with a password, the API will return
 
 In this case, it might not be a problem, becase the user himself is sending the password.
 
-But if we use sthe same model for another endpoint, we could be sending the passwords of our users to every client.
+But if we use sthe same model for another path operation, we could be sending the passwords of our users to every client.
 
 !!! danger
     Never send the plain password of a user in a response.
@@ -55,7 +55,7 @@ We can instead create an input model with the plaintext password and an output m
 {!./tutorial/src/response-model/tutorial003.py!}
 ```
 
-Here, even though our endpoint function is returning the same input user that contains the password:
+Here, even though our path operation function is returning the same input user that contains the password:
 
 ```Python hl_lines="23"
 {!./tutorial/src/response-model/tutorial003.py!}
@@ -81,4 +81,4 @@ And both models will be used for the interactive API documentation:
 
 ## Recap
 
-Use the endpoint decorator's parameter `response_model` to define response models and especially to ensure private data is filtered out.
+Use the path operation decorator's parameter `response_model` to define response models and especially to ensure private data is filtered out.