Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rephrase the documentation to avoid the word "compromise" and use direct language #650

Closed
wants to merge 3 commits into from
Closed

Rephrase the documentation to avoid the word "compromise" and use direct language #650

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1d2ff1d
Replace usages of 'compromise' and use assertive language
lbenitez000 Sep 27, 2023
8bce484
Titleize
lbenitez000 Sep 27, 2023
1d08683
Merge branch 'main' into doc-compromise-rephrase
tiangolo Oct 23, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/tutorial/fastapi/multiple-models.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,17 +53,17 @@ Here's the weird thing, the `id` currently seems also "optional". 🤔

This is because in our **SQLModel** class we declare the `id` with `Optional[int]`, because it could be `None` in memory until we save it in the database and we finally get the actual ID.

But in the responses, we would always send a model from the database, and it would **always have an ID**. So the `id` in the responses could be declared as required too.
But in the responses, we must always send a model from the database, and it must **always have an ID**. So the `id` in the responses must also be declared as required.

This would mean that our application is making the compromise with the clients that if it sends a hero, it would for sure have an `id` with a value, it would not be `None`.
This means that our application is making the promise to the clients that if it sends a hero, it will for sure have an `id` with a value, it will not be `None`.

### Why Is it Important to Compromise with the Responses
### Why Is it Important to Have a Contract for Responses

The ultimate goal of an API is for some **clients to use it**.

The clients could be a frontend application, a command line program, a graphical user interface, a mobile application, another backend application, etc.

And the code those clients write depends on what our API tells them they **need to send**, and what they can **expect to receive**.
And the code those clients write depends on what our API tells them they **need to send**, and what they must **expect to receive**.

Making both sides very clear will make it much easier to interact with the API.

Expand Down