# Первые шаги
Самый простой FastAPI файл может выглядеть так:
```Python
{!../../../docs_src/first_steps/tutorial001.py!}
```
Скопируйте в файл `main.py`.
Запустите сервер в режиме реального времени:
```console
$ uvicorn main:app --reload
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [28720]
INFO: Started server process [28722]
INFO: Waiting for application startup.
INFO: Application startup complete.
```
!!! note "Технические детали"
Команда `uvicorn main:app` обращается к:
* `main`: файл `main.py` (модуль Python).
* `app`: объект, созданный внутри файла `main.py` в строке `app = FastAPI()`.
* `--reload`: перезапускает сервер после изменения кода. Используйте только для разработки.
В окне вывода появится следующая строка:
```hl_lines="4"
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
Эта строка показывает URL-адрес, по которому приложение доступно на локальной машине.
### Проверьте
Откройте браузер по адресу: http://127.0.0.1:8000.
Вы увидите JSON-ответ следующего вида:
```JSON
{"message": "Hello World"}
```
### Интерактивная документация API
Перейдите по адресу: http://127.0.0.1:8000/docs.
Вы увидите автоматически сгенерированную, интерактивную документацию по API (предоставленную Swagger UI):
### Альтернативная документация API
Теперь перейдите по адресу http://127.0.0.1:8000/redoc.
Вы увидите альтернативную автоматически сгенерированную документацию (предоставленную ReDoc):
### OpenAPI
**FastAPI** генерирует "схему" всего API, используя стандарт **OpenAPI**.
#### "Схема"
"Схема" - это определение или описание чего-либо. Не код, реализующий это, а только абстрактное описание.
#### API "схема"
OpenAPI - это спецификация, которая определяет, как описывать схему API.
Определение схемы содержит пути (paths) API, их параметры и т.п.
#### "Схема" данных
Термин "схема" также может относиться к формату или структуре некоторых данных, например, JSON.
Тогда, подразумеваются атрибуты JSON, их типы данных и т.п.
#### OpenAPI и JSON Schema
OpenAPI описывает схему API. Эта схема содержит определения (или "схемы") данных, отправляемых и получаемых API. Для описания структуры данных в JSON используется стандарт **JSON Schema**.
#### Рассмотрим `openapi.json`
Если Вас интересует, как выглядит исходная схема OpenAPI, то FastAPI автоматически генерирует JSON-схему со всеми описаниями API.
Можете посмотреть здесь: http://127.0.0.1:8000/openapi.json.
Вы увидите примерно такой JSON:
```JSON
{
"openapi": "3.0.2",
"info": {
"title": "FastAPI",
"version": "0.1.0"
},
"paths": {
"/items/": {
"get": {
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
...
```
#### Для чего нужен OpenAPI
Схема OpenAPI является основой для обеих систем интерактивной документации.
Существуют десятки альтернативных инструментов, основанных на OpenAPI. Вы можете легко добавить любой из них к **FastAPI** приложению.
Вы также можете использовать OpenAPI для автоматической генерации кода для клиентов, которые взаимодействуют с API. Например, для фронтенд-, мобильных или IoT-приложений.
## Рассмотрим поэтапно
### Шаг 1: импортируйте `FastAPI`
```Python hl_lines="1"
{!../../../docs_src/first_steps/tutorial001.py!}
```
`FastAPI` это класс в Python, который предоставляет всю функциональность для API.
!!! note "Технические детали"
`FastAPI` это класс, который наследуется непосредственно от `Starlette`.
Вы можете использовать всю функциональность Starlette в `FastAPI`.
### Шаг 2: создайте экземпляр `FastAPI`
```Python hl_lines="3"
{!../../../docs_src/first_steps/tutorial001.py!}
```
Переменная `app` является экземпляром класса `FastAPI`.
Это единая точка входа для создания и взаимодействия с API.
Именно к этой переменной `app` обращается `uvicorn` в команде:
```console
$ uvicorn main:app --reload
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
Если создать такое приложение:
```Python hl_lines="3"
{!../../../docs_src/first_steps/tutorial002.py!}
```
И поместить его в `main.py`, тогда вызов `uvicorn` будет таким:
```console
$ uvicorn main:my_awesome_api --reload
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
### Шаг 3: определите *операцию пути (path operation)*
#### Путь (path)
"Путь" это часть URL, после первого символа `/`, следующего за именем домена.
Для URL:
```
https://example.com/items/foo
```
...путь выглядит так:
```
/items/foo
```
!!! info "Дополнительная иформация"
Термин "path" также часто называется "endpoint" или "route".
При создании API, "путь" является основным способом разделения "задач" и "ресурсов".
#### Операция (operation)
"Операция" это один из "методов" HTTP.
Таких, как:
* `POST`
* `GET`
* `PUT`
* `DELETE`
...и более экзотических:
* `OPTIONS`
* `HEAD`
* `PATCH`
* `TRACE`
По протоколу HTTP можно обращаться к каждому пути, используя один (или несколько) из этих "методов".
---
При создании API принято использовать конкретные HTTP-методы для выполнения определенных действий.
Обычно используют:
* `POST`: создать данные.
* `GET`: прочитать.
* `PUT`: изменить (обновить).
* `DELETE`: удалить.
В OpenAPI каждый HTTP метод называется "**операция**".
Мы также будем придерживаться этого термина.
#### Определите *декоратор операции пути (path operation decorator)*
```Python hl_lines="6"
{!../../../docs_src/first_steps/tutorial001.py!}
```
Декоратор `@app.get("/")` указывает **FastAPI**, что функция, прямо под ним, отвечает за обработку запросов, поступающих по адресу:
* путь `/`
* использующих get операцию
!!! info "`@decorator` Дополнительная информация"
Синтаксис `@something` в Python называется "декоратор".
Вы помещаете его над функцией. Как красивую декоративную шляпу (думаю, что оттуда и происходит этот термин).
"Декоратор" принимает функцию ниже и выполняет с ней какое-то действие.
В нашем случае, этот декоратор сообщает **FastAPI**, что функция ниже соответствует **пути** `/` и **операции** `get`.
Это и есть "**декоратор операции пути**".
Можно также использовать операции:
* `@app.post()`
* `@app.put()`
* `@app.delete()`
И более экзотические:
* `@app.options()`
* `@app.head()`
* `@app.patch()`
* `@app.trace()`
!!! tip "Подсказка"
Вы можете использовать каждую операцию (HTTP-метод) по своему усмотрению.
**FastAPI** не навязывает определенного значения для каждого метода.
Информация здесь представлена как рекомендация, а не требование.
Например, при использовании GraphQL обычно все действия выполняются только с помощью POST операций.
### Шаг 4: определите **функцию операции пути**
Вот "**функция операции пути**":
* **путь**: `/`.
* **операция**: `get`.
* **функция**: функция ниже "декоратора" (ниже `@app.get("/")`).
```Python hl_lines="7"
{!../../../docs_src/first_steps/tutorial001.py!}
```
Это обычная Python функция.
**FastAPI** будет вызывать её каждый раз при получении `GET` запроса к URL "`/`".
В данном случае это асинхронная функция.
---
Вы также можете определить ее как обычную функцию вместо `async def`:
```Python hl_lines="7"
{!../../../docs_src/first_steps/tutorial003.py!}
```
!!! note "Технические детали"
Если не знаете в чём разница, посмотрите [Конкурентность: *"Нет времени?"*](../async.md#in-a-hurry){.internal-link target=_blank}.
### Шаг 5: верните результат
```Python hl_lines="8"
{!../../../docs_src/first_steps/tutorial001.py!}
```
Вы можете вернуть `dict`, `list`, отдельные значения `str`, `int` и т.д.
Также можно вернуть модели Pydantic (рассмотрим это позже).
Многие объекты и модели будут автоматически преобразованы в JSON (включая ORM). Пробуйте использовать другие объекты, которые предпочтительней для Вас, вероятно, они уже поддерживаются.
## Резюме
* Импортируем `FastAPI`.
* Создаём экземпляр `app`.
* Пишем **декоратор операции пути** (такой как `@app.get("/")`).
* Пишем **функцию операции пути** (`def root(): ...`).
* Запускаем сервер в режиме разработки (`uvicorn main:app --reload`).