Фаст апи что это
Знакомство с FastAPI
Это неофициальный перевод документации FastAPI. Если у вас есть время и знания, можете помочь с официальным переводом здесь.
Введение
Весь использованный код можно копировать и использовать без изменений (этот код представляет собой проверенные python-файлы).
Для запуска любого из примеров нужно скопировать код в файл main.py и запустить uvicorn с помощью следующей команды:
Крайне рекомендуется писать или копировать код и запускать локально. Использование его в редакторе показывает основные преимущества FastAPI. Можно видеть, насколько мало кода нужно писать: все проверки типов, автозаполнения и так далее.
Установка FastAPI
Первый шаг — установка FastAPI.
При первом знакомстве лучше установить его вместе со всеми опциональными зависимостями и возможностями:
… что также включает uvicorn, который может быть использован как сервер для запуска кода.
Можно также выполнить установку частями. Это может потребоваться при развертывании приложения:
pip install fastapi
Также нужно установить uvicorn, чтобы он работал как сервер:
pip install uvicorn
И так для каждой зависимости.
Первый запуск приложения
Простейший файл FastAPI может выглядеть вот так:
Скопируйте содержимое в файл main.py и запустите сервер:
В выводе есть такая строка:
Она показывает URL работы сервера на локальной машине.
Проверка работы
Перейдите в браузере по ссылке http://127.0.0.1:8000. Там отобразится ответ в формате JSON:
Автоматическая документация API
Теперь стоит перейти на http://127.0.0.1:8000/docs.
На этой странице находится интерактивная документация по API (предоставляемая Swagger UI):
Альтернативная документация API
Также можно попробовать http://127.0.0.1:8000/redoc.
Это альтернативный вариант автоматической документации (от ReDoc):
OpenAPI
FastAPI генерирует «схему» из API с помощью стандарта OpenAPI.
Схема
Схема (schema) — это определение или описание чего-либо. Не код, отвечающий за реализацию, а просто абстрактное описание.
API-схема
В этом случае OpenAPI — это спецификация, которая предписывает, как именно определять схему API. Определение включает пути, возможные принимаемые параметры и так далее.
Схема данных
Понятие «схема» может также указывать на форму некоторых данных: например, JSON-содержимое. В этом случае тут будут указываться JSON-атрибуты, использованные типы данных и другое.
OpenAPI и JSON Schema
OpenAPI определяет схему API для созданного API. А она, в свою очередь, включает определения отправленных или полученных через API данных с помощью JSON — стандарта схем данных JSON.
Проверка openapi.json
Если интересно узнать, как работает чистая схема OpenAPI, то FastAPI автоматически генерирует JSON-схему с описаниями API.
Их можно увидеть прямо на сайте: http://127.0.0.1:8000/openapi.json. Там будет показан JSON в таком формате:
Для чего нужен OpenAPI
Схема OpenAPI — это то, что отвечает за работу двух включенных интерактивных систем документации.
И есть десятки альтернатив, все из которых основаны на OpenAPI. Их можно запросто добавлять в приложение, построенное с помощью FastAPI.
Его также можно использовать для автоматической генерации кода, чтобы у клиентов была возможность взаимодействовать через API. Например, для фронтенда, мобильных или IoT-приложений.
Из чего состоит наше приложение
Шаг №1: импорт FastAPI
FastAPI — это класс Python, который предоставляет всю функциональность для API.
Знакомство с FastAPI
В нашей команде бытует хорошая практика фиксировать всё изменения, которые отправляются в продакшен в гитхабовских релизах. Однако, не вся наша команда имеет доступ в гитхаб, а о релизах хочется знать всем. Так сложилась традиция релиз из гитхаба дублировать в рабочем чате команды в телеграме. Что хорошо, гитхаб позволяет с помощь маркдауна красиво оформить релиз с разделением на секции и ссылками на задачи, которые отправляются на выкатку. Что плохо, простым copy/paste всю эту красоту в телеграм не перенесёшь и приходится тратить время на довольно нудную работу по повторному оформлению релиза, но уже в телеграме. Ну а посколько программисты народ ленивый, я решил этот процесс автоматизировать.
Исходные данные:
Соответственно, задача заключается в том, чтобы поднять HTTP API, который сможет принять POST запрос, проверить подпись, извлечь нужную информацию из тела запроса и передать её дальше по инстанции. Как тут не попробовать FastAPI, на который я давно глаз положил?
Кто такой FastAPI?
FastAPI — это фреймворк для создания лаконичных и довольно быстрых HTTP API-серверов со встроенными валидацией, сериализацией и асинхронностью,
что называется, из коробки. Стоит он на плечах двух других фреймворков: работой с web в FastAPI занимается Starlette, а за валидацию отвечает Pydantic.
Комбайн получился легким, неперегруженным и более, чем достаточным по функционалу.
Необходимый минимум
Для работы FastAPI необходим ASGI-сервер, по дефолту документация предлагает uvcorn, базирующийся на uvloop, однако FastAPI также может работать и с другими серверами, например, c hypercorn
Вот мои зависимости:
И этого более чем достаточно.
Для более тщательных читателей в конце статьи есть ссылка на репозиторий с ботом, там можно посмотреть на зависимости для разработки и тестирования.
Собираем API
Надо заметить, что подход к оформлению хэндлеров в FastAPI чрезвычайно напоминает такой же в Flask, Bottle, да тысячи их. Видимо, миллионы мух не могут-таки ошибаться.
В самом первом приближении мой роут для обработки релиза выглядел так:
Здесь прекрасно видно, как выглядят модели Pydantic. Их можно вкладывать, причем как сущностями, так и списками, к примеру так:
Ещё мы обязаны задать типы полям моделей и FastAPI будет мапить входящий запрос на переданную ему модель с учётом типов. В случае несовпадения он отдаст ошибку валидации. В случае, если поля во входящих данных нет и в модели не проставлено значение по-умолчанию — тоже.
Кроме базовых питоньих типов Pydantic предлагает ещё достаточно много своих собственных типов данных, в моём примере это тип HttpUrl, то есть входящая строка должна быть валидным URL со схемой и доменом первого уровня, в противном случае FastAPI отдаст ошибку валидации. Остальные типы Pydantic можно посмотреть здесь
Таким образом валидация и сериализация данных настраивается уже при задании модели данных.
Аутентификация
FastAPI поддерживает достаточно методов аутентификации по умолчанию, но, поскольку здесь используется гитхабовская подпись запроса, авторизацию пришлось колхозить самостоятельно,
ну да оно и к лучшему — больше интересного!
Я вынес роуты FastAPI в отдельный роутер, а в основном файле оставил авторизацию и управление документацией:
Обратите внимание, что request.body — это функция, причем асинхронная. В FastAPI(а на деле в Starlette) асинхронность везде, это надо обязательно помнить.
Что касается документации, то это ещё один большой плюс FastAPI — он автоматически генерит документацию в формате OpenAPI и отдаёт её в формате Swagger/ReDoc в зависимости от где вы смотрите, ваш_сайт/docs или ваш_сайт/redoc соответственно.
В моем случае я решил документацию в проде вообще убрать. Ну его.
Соответственно, файл с роутами превратился в это:
А всё
Это действительно весь код, который запускает быстрый HTTP API-сервер с аутентификацией, валидацией и документацией.
Итого
FastAPI — действительно отличный инструмент, если вам по душе лаконичность и, вместе с тем, понятность кода. Кроме того, он асинхронен(фу, вы что, в 2020-ом году пишете синхронный код?
я тоже), быстр и это не идёт в ущерб функциональности.
Так что если на горизонте маячит новый проект, для которого важны производительность, документация и валидация, то, вероятно, имеет смысл посмотреть в сторону FastAPI.
Вместо послесловия
Конечно, проект получился несколько больше, чем описанные мной три файла. Там их на самом деле шесть — собственно бот, описывать которого я не стал, ибо нерелевантно, а также утилиты и настройки, вынесенные в отдельные файлы для большего порядку.
Всё это, а также тесты, докерфайл и настройку github actions вы можете посмотреть в исходном коде проекта
FastAPI
FastAPI framework, high performance, easy to learn, fast to code, ready for production
FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.6+ based on standard Python type hints.
The key features are:
Fast: Very high performance, on par with NodeJS and Go (thanks to Starlette and Pydantic). One of the fastest Python frameworks available.
Fast to code: Increase the speed to develop features by about 200% to 300%. *
* estimation based on tests on an internal development team, building production applications.
Sponsors¶
Opinions¶
«[. ] I’m using FastAPI a ton these days. [. ] I’m actually planning to use it for all of my team’s ML services at Microsoft. Some of them are getting integrated into the core Windows product and some Office products.«
«We adopted the FastAPI library to spawn a REST server that can be queried to obtain predictions. [for Ludwig]«
«Netflix is pleased to announce the open-source release of our crisis management orchestration framework: Dispatch! [built with FastAPI]«
«I’m over the moon excited about FastAPI. It’s so fun!«
«If you’re looking to learn one modern framework for building REST APIs, check out FastAPI [. ] It’s fast, easy to use and easy to learn [. ]«
«We’ve switched over to FastAPI for our APIs [. ] I think you’ll like it [. ]«
Typer, the FastAPI of CLIs¶
Typer is FastAPI’s little sibling. And it’s intended to be the FastAPI of CLIs. ⌨️ 🚀
Requirements¶
FastAPI stands on the shoulders of giants:
Installation¶
You will also need an ASGI server, for production such as Uvicorn or Hypercorn.
Example¶
Create it¶
Note:
If you don’t know, check the «In a hurry?» section about async and await in the docs.
Run it¶
Run the server with:
The command uvicorn main:app refers to:
Check it¶
You will see the JSON response as:
You already created an API that:
Interactive API docs¶
You will see the automatic interactive API documentation (provided by Swagger UI):
Alternative API docs¶
You will see the alternative automatic documentation (provided by ReDoc):
Example upgrade¶
Now modify the file main.py to receive a body from a PUT request.
Declare the body using standard Python types, thanks to Pydantic.
Interactive API docs upgrade¶
Alternative API docs upgrade¶
Recap¶
In summary, you declare once the types of parameters, body, etc. as function parameters.
You do that with standard modern Python types.
You don’t have to learn a new syntax, the methods or classes of a specific library, etc.
Just standard Python 3.6+.
For example, for an int :
or for a more complex Item model:
. and with that single declaration you get:
Coming back to the previous code example, FastAPI will:
We just scratched the surface, but you already get the idea of how it all works.
Try changing the line with:
. and see how your editor will auto-complete the attributes and know their types:
Performance¶
Independent TechEmpower benchmarks show FastAPI applications running under Uvicorn as one of the fastest Python frameworks available, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*)
To understand more about it, see the section Benchmarks.
Optional Dependencies¶
Used by FastAPI / Starlette:
License¶
This project is licensed under the terms of the MIT license.
Почему Вы должны попробовать FastAPI?
Лого взято из Github репозитория FastAPI
FastAPI — относительно новый веб-фреймворк, написанный на языке программирования Python для создания REST (а если сильно постараться то и GraphQL) API, основанный на новых возможностях Python 3.6+, таких как: подсказки типов (type-hints), нативная асинхронность (asyncio). Помимо всего прочего, FastAPI плотно интегрируется с OpenAPI-schema и автоматически генерирует документацию для вашего API посредством Swagger и ReDoc
FastAPI построен на базе Starlette и Pydantic.
Starlette — ASGI микро-фреймворк для написания веб-приложений.
Pydantic — библиотека для парсинга и валидации данных основанная на Python type-hints.
Что говорят о FastAPI?
«[. ] Я использую FastAPI очень часто в последние дни. [. ] Я однозначно планирую использовать его для всех ML сервисов моей команды в Microsoft. Некоторые из них интегрируются в Windows и некоторые продукты Office.»
Kabir Khan — Microsoft (ref)
«Если вы хотите выучить ещё один фреймворк для написания REST API, взгляните на FastAPI [. ] Он быстрый, прост в использовании и изучении. [. ]»
«Теперь мы используем FastAPI для наших API [. ] Я думаю он вам понравится! [. ]»
Ines Montani — Matthew Honnibal — Explosion AI founders — spaCy creators (ref) — (ref)
Минимальное API созданное с помощью FastAPI
Я постараюсь показать Вам как создать простое, но в то же время полезное API с документацией для разработчиков. Мы будем писать генератор случайных фраз!
Установка необходимых компонентов
Новый модуль!
Uvicorn — это ASGI-совместимый веб-сервер, который мы будем использовать для запуска нашего приложения.
Для начала создадим основу нашего приложения.
Это приложение уже работает и его можно запустить.
Пропишите данную команду в вашем терминале и откройте страничку в браузере по адресу http://127.0.0.1:8000/docs.
Но пока в нашем приложении не обозначено ни одного эндпоинта — давайте это исправим!
База данных
Создадим файл db.py и начнём писать код.
Импортируем необходимые модули:
После — обозначим две модели: входная фраза (та, которую нам будет отправлять пользователь) и «выходная» (та, которую мы будем отправлять пользователю).
После этого, создадим простой класс для работы с БД:
Теперь можно приступить к написанию самого API.
Создадим файл main.py и импортируем следующие модули:
Инициализируем наше приложение и базу данных:
И напишем простой метод получения случайной фразы!
Как Вы можете заметить, в декораторе я также указываю некоторые другие значения, нужные для генерации более красивой документации 🙂 В официальной документации Вы можете посмотреть на все возможные параметры.
В этом куске кода, мы пытаемся получить случайную фразу из базы данных, а если база данных пуста — возвращаем ошибку с кодом 404.
Аналогично пишем другие методы:
И всё! Наше маленькое, но полезное API — готово!
Теперь мы можем запустить приложение с помощью uvicorn, открыть интерактивную документацию (http://127.0.0.1/docs) и попробовать наше API!
Полезные материалы
Конечно, я не смог рассказать Вам о всех возможностях FastAPI, например таких как: умная DI система, middlewares, куки, стандартные методы аутентификация в API (jwt, oauth2, api-key) и многое другое!
Но целью этой статьи является не столько обзор всех возможностей этого фреймворка, а сколько толчок Вас изучить его самим. FastAPI имеет замечательную документацию с кучей примеров.
Создавайте и размещайте приложения Fast Data Science с помощью FastAPI
Недавно я разместил ряд готовых приложений для обработки данных в виде веб-служб Restful с использованием веб-инфраструктуры FastAPI.
Я обнаружил, что FastAPI стабилен и прост в использовании, и по этим причинам я решил написать статью о библиотеке FastAPI, описывающую шаги, которые мы можем выполнить, чтобы разместить приложение для обработки данных.
FastAPI был выпущен в 2018 году и становится де-факто выбором для создания высокопроизводительных приложений для обработки данных.
Эта статья объяснит, что такое FastAPI, почему он превосходит своих конкурентов, а также пошаговое руководство о том, как разместить приложение для обработки данных с использованием FastAPI.
1. Что такое FastAPI?
Как видно из названия, FastAPI является высокопроизводительной веб-инфраструктурой. Его производительность можно сравнить с NodeJS и Go, и он считается одним из самых быстрых доступных сред Python.
Netflix, Uber, Microsoft и многие другие корпорации используют библиотеку FastAPI.
FastAPI может помочь нам создать API с Python 3.6+.
Он основан на стандартных подсказках типа Python. FastAPI не только интуитивно понятен и прост в использовании в проектах, но и код FastAPI также покрывает 100% тестов, и, следовательно, это готовый к работе надежный код.
Пользуясь Flask уже довольно давно, я заметил, что FastAPI так же прост в использовании, как Flask. Фактически, FastAPI адаптировал свою простоту от Flask API. Впоследствии, в общем, я рекомендую изучить FastAPI для будущих проектов.
FastAPI построен на библиотеках Starlette и Pydantic.
Диаграмма показывает, что FastAPI использует Starlette для своих веб-частей и Pydantic для частей данных.
Давайте рассмотрим особенности FastAPI.
2. Основные функции FastAPI
FastAPI основан на открытых стандартах для OpenAPI и JSON Schema. В результате он может автоматически создавать SwaggerUI для нашего веб-API без какого-либо дополнительного кодирования, если мы используем соответствующие типы данных Pydantic. SwaggerUI является интерактивным по своей природе и позволяет нам тестировать API непосредственно из браузера. Автоматическая документация была вдохновлена APISpec.
Я продемонстрирую, как мы можем построить документацию по автоматической модели данных с помощью схемы JSON, используя FastAPI, позже в этой статье.
FastAPI также позволяет нам проверять входные данные от внешних абонентов и генерирует автоматические ошибки для клиентов, когда он получает недействительные данные. Функция документирования была основана на DEST-среде Django.
OpenAPI автоматически генерирует схему для приложения. FastAPI также поддерживает сериализацию данных и анализ входных данных, которые были вдохновлены Marshmallow и Webargs.
Крайне важно создать веб-API, который не блокирует своих абонентов во время выполнения операций. Библиотека asyncio в Python предлагает большое количество асинхронных возможностей.
Библиотека FastAPI поддерживает асинхронные операции ввода-вывода. Это стало возможным благодаря тому, что FastAPI основан на библиотеке Starlette.
В отличие от сервера WSGI, серверы ASGI могут поддерживать HTTP / 2 и WebSockets. С помощью Uvicorn мы можем создать веб-API, который может обеспечить высокую пропускную способность в контексте ввода-вывода.
Starlette использует более новый сервер ASGI асинхронного ввода-вывода и также поддерживает фоновые задачи. Следовательно, мы можем создавать быстрые веб-API с малой латентностью, используя FastAPI
3. Самая важная особенность; мы можем быстро создать конечные точки REST для нашего приложения для обработки данных
Пользователи Flask должны установить пакет Flask-restplus, чтобы создать конечные точки REST для своего приложения для обработки данных.
FastAPI поддерживает Rest операции GET, PUT, POST, DELETE, OPTIONS, HEAD, PATCH и TRACE без каких-либо дополнительных пакетов. Все маршруты вместе с их операциями автоматически генерируются в документации.
4. Приложение FastAPI легко установить, использовать и поддерживать.
Недавно я заметил закономерность в отрасли. Становится жизненно важным быстро вывести решение для обработки данных на рынок. Кроме того, приложения для обработки данных являются одним из компонентов большой экосистемы, и им необходимо взаимодействовать с рядом служб и интерфейсов. Это означает, что крайне важно иметь возможность быстрого развертывания приложения в виде веб-службы, чтобы его могли использовать конечные пользователи.
FastAPI прост в использовании. Буквально за минуты требуется разместить приложение для обработки данных в качестве микросервиса и предоставить конечные точки, которые могут вызывать другие приложения. Проверка и обработка ошибок среди других функций API выходят из коробки, что может помочь в повышении удовлетворенности клиентов и надежности приложения.
Это подводит нас к последнему разделу статьи, где я продемонстрирую шаги для размещения приложения.
3. Пошаговая реализация
Давайте начнем с реального варианта использования для создания интеллектуального приложения для обработки данных.
USECASE
1. Создайте виртуальную среду
2. Установите зависимости
Следующим шагом является установка необходимых модулей.
Во-первых, установите фастапи
В результате он также установит необходимые зависимости, такие как starlette == 0.13.4 и pydantic == 1.5.1.
Затем установите Uvicorn
Теперь, чтобы почистить веб-страницы, я собираюсь использовать библиотеку Pandas. Поэтому следующим шагом является установка pandas:
Давайте создадим структуру папок.
3. Создать структуру проекта
Для простоты давайте создадим следующую структуру папок.
Мы создали две папки: SmartApp и src в папке SmartApp. Кроме того, давайте создадим следующие три пустых Python файла:
Если вы хотите создать готовое к использованию решение, то я рекомендую использовать проект python cookie-cutter. Доступно много шаблонов, включая один, предназначенный для FastAPI.
Убедитесь, что виртуальная среда активирована.
4. Реализация кода Python
Следующий шаг включает в себя реализацию кода Python.
models.py
Откройте файл models.py и добавьте следующий код:
workflow_runner.py
Теперь, когда модели реализованы, давайте добавим код в workflow_runner.py. Это ядро нашего приложения для обработки данных.
Этот файл будет содержать код для выполнения следующих двух шагов:
Обратите внимание, что метод run() в workflow_controller был объявлен как асинхронный, чтобы проиллюстрировать, как мы можем создать неблокирующую асинхронную операцию ввода-вывода.
Если мы выберем Dow Jone, это вызовет исключение. Это поможет мне продемонстрировать, как мы можем отображать дружественные пользователю ошибки.
Теперь мы готовы интегрировать FastAPI.
main.py
Наконец, мы собираемся добавить код в файл main.py
Сначала добавьте импорт:
Затем создайте экземпляр FastAPI() и объявите его как переменную приложения.
Мы даем ему название, описание и версию. Эта информация будет автоматически отображаться в документации.
Предоставьте конечную точку GET для обработки запроса, который вызывает workflow_runner.run() :
Обратите внимание, как я ожидаю на запуск функции.
Мы также можем пометить параметры запроса как необязательные, и документация будет автоматически отражена с учетом изменений. Мы объявили title значение метаданных для индекса параметра пути. Это появится в автоматической документации.
Обратите внимание, функция get_result() объявлена как асинхронная. Это позволяет нам обслуживать запросы, не блокируя другие вызовы.
В результате эта функция позволяет приложению обслуживать запросы одновременно.
Последнее, на что следует обратить внимание, это то, что все исключения перехвачены, а затем возникает MyException.
Хотя лучшая практика заключается в том, чтобы явно перехватывать исключения и разбираться с ними по отдельности, но для демонстрационной цели, я перехватываю все исключения с помощью try / except.
Наконец, для обработки ошибок мы определяем конечную точку, которая может обрабатывать исключения типа MyException.
Наконец, добавьте код для запуска сервера uvicorn.
Мы закончили с реализацией.
5. Запуск серверного приложения
Давайте запустим приложение. Перейдите в папку, где находится main.py, и выполните следующую строку в терминале:
Reload позволит перезапустить сервер после изменения коды, которые позволяют быстрое развитие в процессе разработки.
Запуск команды покажет:
6. Использование Сервиса
Во-первых, давайте рассмотрим автоматическую документацию API
Он отобразит пользовательский интерфейс Swagger.
При нажатии на index отображается список указателей:
При запуске он показывает названия компаний в ответе:
Давайте выберем Dow Jones и посмотрим, получим ли мы дружественную ошибку:
Это было сделано автоматически FastAPI.
Вызов приложения Smart Data Science из другого приложения
Мы можем позвонить Curl:
Мы можем открыть браузер и перейти к URL-адресу для просмотра ответа:
Вы можете скачать спецификацию openAPI, перейдя по ссылке:
Мы видим, что проверка была встроена вместе с допустимыми значениями индекса, как показано ниже. Схема OpenAPI поддерживает интерфейс Swagger. Он включает в себя API и схему данных, как показано ниже:
Это документация OpenAPI для API, автоматически созданного FastAPI. Мы можем отправить его вызывающим сторонам API, чтобы они могли легко интегрировать свои услуги с нашим решением.
Обратите внимание, что члены перечисления индекса появляются в документации OpenAPI вместе с заголовком параметра и правилами проверки.