Проектирование REST API / OpenAPI (TypeSpec) / Кеширование / Денис Семененко / #17

Рет қаралды 11,374

Организованное программирование | Кирилл Мокевнин

Күн бұрын

Пікірлер: 57

@mokevnin Ай бұрын

Какой подход вы предпочитаете? Code First или Design First?

@artemsokolov5007 Ай бұрын

предпочитаю Coffee First

@MrLotrus Ай бұрын

Design First. Но это редкая птица в моих краях.

@batazor Ай бұрын

Скорее contract-first, по крайне мере в ru-сегменте

@nickt692 Ай бұрын

К сожалению в реальном мире Design First перестает работать после релиза первой версии

@artemsokolov5007 Ай бұрын

@@nickt692 с чего вдруг? спокойно дизайнишь вторую версию или обратно совместимую вторую. вроде никаких проблем нет дизайнить

@SergeyZarin 19 сағат бұрын

Ребята, огромное спасибо за этот полезный во всем смыслах выпуск! Побольше бы таких!

@badgerrimo Ай бұрын

Посмотрел на одном дыхании, буду еще раз, уже с поиском того, о чем говорят. Если есть такая возможность, в следующих выпусках попробуйте маркировать текстом термины и названия сервисов где-нибудь в углу экрана.

@bellajam9993 Ай бұрын

Очень грамотно делаете, очень интересно смотреть, Спасибо Вам)))

@pumbo_nv 29 күн бұрын

Кирилл, спасибо что радуете нас интересным и познавательным контентом. Очень хотел бы увидеть выпуск про DDD.

@artemsokolov5007 Ай бұрын

выпуск топ, в самое сердечко TypeSpec, Spotlight и книжку прям записал, мб внедрю в команде даж было бы еще интересно про event driven историю послушать и про спецификации/бестпрактисы в этой области

@goldobin1 27 күн бұрын

Ребята, вы отлично погружены и я во многих частях с вамиполностью согласен. Про RPC и REST просто огонь. Не раскрыта тема заворачивания RPC в REST, зато отлично подметили про HPPP 2/0 c REST. По хорошему, можно на несколько выпусков разбивать и объяснять более подробно. Например, ведущему местами прикинуться чайником и попросить эксперта рассказать в нескольких предложениях о какой-нибудь дилемме.

@egorsm00 Ай бұрын

О, а я с ним работаю кстати. Слушайте, что Денис говорит, он фигни не скажет

@sonboy520 Ай бұрын

Вот это духота, жесть конечно, но полезно

@7nolikov 20 күн бұрын

Наконец-то про стандарты API

@AKAAAAAAAAAAAAAA Ай бұрын

ребята, спасибо за рекомендацию книги. за всеми коммерческими книгами слежу, а бесплатного слона и не приметил

@alex4everyours Ай бұрын

Классный выпуск, крайне насыщенный и очень полезный. Огромное спасибо! 👍 Про Fastify и как его наилучшим образом использовать (с его плагинами) было бы и дальше интересно посмотреть и послушать.

@eugene_elchugin Ай бұрын

Когда речь идет про API для фронтенда, то думаю более правильно выделять отдельный BFF сервис, который реализует тот интерфейс, который нужен фронту. По сути фронтенд диктуен интерфейс, которым ему удобнее пользоваться. Именно BFF агрегирует все необходимые данные от поставщиков данных, мапит их на фронтовые модели.

@testme4640 29 күн бұрын

Самое простое решение: Контракты на typescript, из которых генерируется json-schema. (В проде 5 лет, 100к mau) На фронте инклудим ts контракты. На бэке валидируем json-схему. Для доков импортим объекты из json-схемы.

@vasiliylu8054 Ай бұрын

Супер, спасибо. Пошел читать)

@Ilya.Vasilyev 20 күн бұрын

Подскажите, пожалуйста, в разделе "Стандарты обработки ошибок в API" вы говорили о RFC 9457 "Problem Details for HTTP APIs"?

@denblackstache 20 күн бұрын

Да, это он

@TheAelyseev Ай бұрын

С одной стороны как обычно много полезного в виде ссылок. С другой стороны API fist вы почти не расскрыли. И в целом получилось очень бессистемно

@Alex-f3m4t Ай бұрын

Отличная тема спасибо

@ЗапасЗнаний Ай бұрын

Что вы сразу к технической теме переходите? Можете сделать плавную подводку с раскрытием гостя? Кто он такой, где учился, сколько программирует, что реализовал

@HalbKartoffel 29 күн бұрын

Зачем коммент с прямой ссылкой на документацию опенсорсной альтернативы Ransack удалили? Hasura в REST тоже умеет, не только GraphQL.

@VoroninPavel Ай бұрын

А чем Ransack от OData отличается, я не понял?

@nickt692 Ай бұрын

OData же от Микрософта? Фу-фу :)

@yuriyvyatkin Ай бұрын

55:30 Всем на заметку. Часто вижу несоответствие.

@sau9703 Ай бұрын

Нужно ли проектировать rest api , если твое апи реализовано на базе odata, graphql , а opeapi юзается с помощью swagger , redoc и т.п. генераторов по метаданным модели ? - это я к тому , что сейчас все пользуются какими-то инструментами , и никто голову себе деталями не забивает , все автоматизировано. (мне вручную ни разу не пришлось описывать сервисы через спеку openapi) По поводу вдохновителей MS , Андерс Хейлсберг основатель тайпскрипта - бывший сотрудник майкрософта , и вдохновлялся он скорее c#-пом (ну как вдохновлялся , он же и участвовал в разработке , откуда часть идей перенес еще и в тайпскрипт) , так что ноги то все растут от мелкософта , они в основном моду и задают на современные фичи.

@artemsokolov5007 Ай бұрын

> и никто голову себе деталями не забивает нанимал как-то человека, который себе голову деталями не забивал он проработал 5 лет программистом на одном фреймворке в одной конторе вышел на рынок и прошел к нам на джуна в вашем случае вы либо все таки проектируете апи, просто используете для этого язык odata, либо не проектируете, а просто пишете код, а потом какое-то апи получается самособой и для вас это просто работает и всех все устраивает. судя по вопросу у вас ситуация №2, а это маркер в сторону того что вы кажется не очень глубоко это понимаете, и при смене работы есть риск потеряться если там будут другие технологии

@7iomka Ай бұрын

Интересно что думаете об Encore.ts? Автогенерация клиента со всеми типами из ендпоинтов, а для ендпоинтов сам пишешь тс-типы для запросов и ответов.

@mokevnin Ай бұрын

Посмотрел. Фичи которые этот фреймворк описывает как основные, есть в fastify (мы частично это как раз обсудили в видео). А целый новый фреймворк из-за этих фич это перебор, такие фреймворки обычно либо умирают либо становятся узко используемыми. Достаточно посмотреть как долго и с какими усилиями тащили fastify наверх

@7iomka Ай бұрын

@@mokevnin Хотелось бы глянуть на ваш код с fastify, я фронтендер и для знакомства с бэком сейчас щупаю именно его. Мне encore приглянулись тем что я знаком с ts, и мне ничего не нужно делать чтобы получить задокументированные валидируемые ендпоинты. К тому же его можно использовать не как фреймворк на полную, а только как api обработчик, оставив в качестве фреймворка то что юзаешь (например у них есть гайды по юзу с nestjs с разной степенью замены фичей) Со многими другими решениями мне нужно опять же прибегать к openApi, и смотреть есть ли у инструменты решения для генерацию в и из (для клиента). У fastify например: Starting with v5, Fastify will require a full JSON schema for the querystring, params and body schema. То есть мне нужно изучить JSON-схему чтобы ею описывать ендпоинты чтобы потом open-api через свагер смог автосгенерировать доку.

@mokevnin Ай бұрын

@@7iomka Там же как раз фишка в том, что json schema писать не надо ручками, она есть в openapi, который автоматически генерируется через typespec, который в свою очередь не привязан к языку. Вот тут пример как оно прокидывается во внутрь, поддерживая все ts штуки: github.com/hexlet-components/js-fastify-rest-api-example

@salexs.7522 Ай бұрын

Что вы думаете о HATEOS?

@oeaoo Ай бұрын

Ненависть. Операционочка.

@tertiumorganum5665 29 күн бұрын

Asyncapi уже не продолжение openapi, они разве что на уровне json schema какую-то совместимость сохранили. Щас версия 3, она сильно поменялась. И да, как раз вебсокет теперь можно. Но вобще async это ужеине рест, это кррль, кафка, редис, то есть не фронтовая тема

@tertiumorganum5665 29 күн бұрын

Выглядит так, как будто несчастные фронтовые люди ушли от типизации, а теперь жутко страдают и придумывают кучу костылей, чтобы типизацию вернуть. В чём проблема Open API генерить код - как минимум интерфейсы для Type скрипта, гошки питона, плюсов?

@davidalexandr5716 17 күн бұрын

Если можно хотелось бы услышать о DDD

@kolserdav Ай бұрын

OpenAPI почему не любят!? Потому что его нужно поддерживать. И TypeSpec не решает эту проблему. Да поудобнее, но всё равно нужно поддерживать. На мой взгляд, тогда уж лучше взять, что-то что умеет преобразовывать типизированные методы в OpenAPI. Если говорить о Typescript, то это что-то вроде `tsoa`. Пишем типизированные методы роутов и преобразуем их в OpenAPI. В общем, нужно идти в сторону генерации OpenAPI из рабочих интерфейсов, тогда API будет всегда актуальным и поддерживать его отдельно не придется.

@denblackstache Ай бұрын

Я так понимаю под словом «поддерживать» имеется в виду термин «синхронизировать». OpenAPI не нужно поддерживать, когда он является единственным источником правды, и на его основе генерируются типы, валидация и т.д. Нужно сначала понять, что важнее для бизнеса Contract-first vs Code-first.

@kolserdav Ай бұрын

@denblackstache суть в том, чтобы API документацию и типы не нужно было синхронизировать отдельно, а делать это в одном месте. И тогда не важно, Code или Contract будет first, и там и там API будет всегда актуальным. Генерировать типы из API тоже можно если в языке нет библиотек, которые делают обратное. Но естественно, это менее удобно чем генерировать OpenAPI из типов.

@aethelweald 29 күн бұрын

Вот и выросло поколение которое и не слышало про CORBA и вообще думают что HTTP придумано для RPC

@gimntut Ай бұрын

Как по мне проблема HATEOAS совсем не в том, что до нужного эндпоинта нужно добираться. В этом смысле HATEOAS ничем не отличается от HTML без CSS и JS. Никто не запрещает хранить url на стороне клиента (см. закладки браузера и вечно открытые вкладки). Никто не мешает поисковикам так же собирать ссылки, чтобы потом пользователь мог перейти сразу на конкретную ссылку. Даже потухающие ссылки не проблема, так же, ка это не является проблемой для html. Главной проблемой HATEOAS является отделение данных от оформления. В обычном API, если нужно нарисовать карту, запрашивается конкретный эндпоинт, который отдаёт данные в фиксированном формате, из которых клиент точно сможет сформировать изображение карты. В html карту нарисует браузер используя css и js. А вот с HATEOAS клиент предположительно ничего не знает, какие эндпоинты и какие данные в эндпоинте могут быть. Если вдруг сервер передаст данные для рисования карты, то как клиент должен догадаться как её нарисовать? Можно заложить в клиент умение рисовать карту. Тогда получается, что клиенту нужно уметь всё что МОЖЕТ случится. В этом смысле, обычные клиенты обычного API сильно выигрывают, т.к. умеют только то, что им доступно из API.

@batazor Ай бұрын

Та с hateoas можно норм работать, в том же ory/Kratos это позволяет рисовать флоу входа от конфигов на сервере, но да клиент должен уметь это отрисовать, но это логично, с рестом точно так же, а если придет что то не то, то в любом случае мы это не отрисуем

@denblackstache Ай бұрын

Полный HATEOAS, где мы начинаем с корневого ресурса, имеет смысл для динамического унифицированного тонкого клиента, который возможно еще и не умеет рендерить самый популярный hypermedia формат - HTML. Да, клиент должен уметь рисовать всё, что может случиться. Поэтому я представляю, что его интерфейс должен быть максимально однотипным, это очень редкий случай. Я упоминал это в видео: на эту роль подходят приложения и сервисы, которые будут использоваться десятилетиями, и скорее всего на стыке интеграции нескольких организаций. Как мне видится это гос сектор, здравоохранение, однотипные формы, реестры и т.д. Большинству приложений достаточно реализовать HATEOAS только в рамках конкретного ресурса, чтобы получить дополнительную гибкость. В блоге Филдинга от 2008 года требования к клиенту, который делает self-discovery всех ресурсов и операций над ними самостоятельно, просто невыполнимы для современных приложений.

@2009Spread Ай бұрын

"Проектирование REST API / OpenAPI (TypeSpec) / Кеширование / Денис Семененко / #17" #### 1. **Введение и история вопроса** - **Описание:** В начале видео Денис Семененко обсуждает историю вопроса, связанного с проектированием REST API и использованием HTTP API или REST. Он упоминает, что когда он спрашивал о REST, многие люди приходили с нравоучениями, вместо того чтобы отвечать на вопросы по теме. - **Вывод:** История вопроса показывает, что REST API часто неправильно понимают и интерпретируют, что приводит к путанице и недопониманию. #### 2. **REST и его ограничения** - **Описание:** Денис обсуждает, что REST не определяет структуру ответов и запросов, что является внутренним вопросом разработчиков. Он также упоминает, что на таком уровне люди часто не задумываются о том, как правильно проектировать API. - **Вывод:** REST предоставляет большую свободу, но это также может привести к несогласованности и сложности в проектировании API. #### 3. **OpenAPI и его использование** - **Описание:** Обсуждается использование OpenAPI для описания API и его преимущества, такие как стандартизация и удобство использования инструментов. Денис также упоминает, что OpenAPI не задает формат сообщений, что оставляет этот вопрос на усмотрение разработчиков. - **Вывод:** OpenAPI - это мощный инструмент для описания API, но он не решает всех вопросов, связанных с форматом сообщений. #### 4. **TypeSpec и его преимущества** - **Описание:** Денис рассказывает о TypeSpec, инструменте от Microsoft, который позволяет компактно описывать API, используя синтаксис, похожий на TypeScript. Он отмечает, что TypeSpec может генерировать различные форматы, включая TypeScript-библиотеки. - **Вывод:** TypeSpec предлагает более удобный и компактный способ описания API, что может упростить разработку и поддержку. #### 5. **Форматы сообщений и стандарты** - **Описание:** Обсуждаются различные форматы сообщений, такие как JSON API, HAL, JSON-LD, и их применение в API. Денис также упоминает о проблемах, связанных с отсутствием общепризнанных стандартов для форматов сообщений. - **Вывод:** Существует множество форматов сообщений, но нет единого стандарта, что создает путаницу и сложности в выборе правильного формата. #### 6. **Проблемы с валидацией и обработкой ошибок** - **Описание:** Денис обсуждает проблемы с валидацией данных и обработкой ошибок в API. Он упоминает о RFC для форматирования ошибок и о том, как правильно обрабатывать ошибки на разных уровнях API. - **Вывод:** Валидация и обработка ошибок - это критически важные аспекты API, которые требуют четкого понимания и стандартизации. #### 7. **Выводы** - **Описание:** В конце видео Денис подводит итоги, обсуждая важность правильного проектирования API, использования стандартов и инструментов, таких как OpenAPI и TypeSpec. Он также подчеркивает необходимость понимания ограничений и возможностей различных форматов сообщений. - **Вывод:** Правильное проектирование API требует глубокого понимания стандартов, инструментов и форматов сообщений. Использование современных инструментов, таких как TypeSpec, может значительно упростить этот процесс. ### Дополнительная информация #### 1. **Ключевые моменты видео:** - Обсуждение истории и ограничений REST API. - Преимущества использования OpenAPI и TypeSpec. - Различные форматы сообщений и их применение. - Проблемы с валидацией и обработкой ошибок. #### 2. **Важные цитаты или высказывания:** - "REST же не определяет структуру ответов, запросов, эта история, уже наше внутреннее." - "Open API описывать, в общем-то, ручками довольно, мягко говоря, напряженное занятие." - "TypeSpec предлагает более удобный и компактный способ описания API."