• Описание конечных точек (эндпойнтов).

• Форматы запросов и ответов.

• Методы аутентификации.

• Обработку ошибок.

• Примеры использования.

Представляем подборку лучших инструментов для создания API-документации.

Swagger

Swagger – один из самых популярных инструментов: он поддерживает много языков программирования и предоставляет удобный интерфейс для проектирования и документирования API. Swagger позволяет определять конечные точки, форматы запросов и ответов, а также методы аутентификации. Кроме того, он предоставляет интерактивные инструменты для исследования и тестирования API.

Apidog

Apidog – комплексный инструмент для разработки, документирования и управления API. Он предлагает автоматическую генерацию интерактивной документации и возможность тестирования API в реальном времени. Apidog также поддерживает генерацию кода на разных языках программирования и предоставляет широкие возможности для настройки стиля документации.

ReDoc

ReDoc – опенсорсный инструмент, поддерживающий спецификации OpenAPI 2.0 и 3.0. Он отлично подходит для публикации интерактивной API-документации и предлагает удобную навигацию с настраиваемым поиском, а также стильный, адаптивный дизайн с возможностью настройки тем.

DapperDox

DapperDox – опенсорсный OpenAPI-рендерер, совместимый с OAS 2.0 и 3.0. Он позволяет использовать контент в формате Markdown для создания диаграмм и предоставляет модуль исследования структуры API для практических экспериментов.

Theneo

Theneo – генератор документации, использующий ИИ для автоматического описания API. У него простой интерфейс, напоминающий Notion, и он поддерживает интеграции с Swagger, Postman и GitHub.

Sphinx

Sphinx – мощный генератор документации, широко используемый в Python-сообществе. Он поддерживает много языков и предлагает широкие возможности для настройки. Sphinx может генерировать документацию в разных форматах, включая HTML, PDF и ePub.

Javadoc

Javadoc специально разработан для документирования Java-кода. Он извлекает комментарии и аннотации из исходного кода для создания HTML-документации с подробным описанием классов, методов и полей.

DocFX

DocFX – генератор статических сайтов, разработанный Microsoft и с ноября 2022 года поддерживаемый сообществом .NET Foundation. Предлагает настраиваемые шаблоны для создания документации и лендингов.

Doxygen

Doxygen поддерживает C++, С, Objective-C, Python, Java, IDL, PHP, C# и Fortran, может генерировать документацию в разных форматах, включая HTML, PDF и LaTeX.

Slate

Slate фокусируется на простоте и удобстве использования, предоставляя удобный, современный, адаптивный интерфейс для API-документации. Он поддерживает Markdown, подсвечивает синтаксис больше 100 языков и предлагает интерактивную консоль для тестирования API-эндпойнтов.

Docusaurus

Docusaurus предназначен для создания современной интерактивной документации и любых других статических сайтов. Он поддерживает все популярные языки, предлагает настраиваемые шаблоны, имеет встроенную функцию поиска на базе Algolia, поддержку локализации и версионирования.

Приглашаем вас на вебинар «Как меняется математика в разных индустриях: от мобильных игр к фондовым рынкам», который состоится 22 августа в 20:00 по МСК. Там вы сможете:

• Узнать, как математические методы влияют на мобильные игры и фондовые рынки.

• Понять различия в математических подходах в разных сферах бизнеса.

• Изучить реальные кейсы применения математики в GameDev и финансах.

• Оценить, какие математические знания необходимы для успешной карьеры в Data Science.

Стать участником вебинара

😎 Автоматизация слепых SQL-инъекций на основе логических значений

Слепая SQL-инъекция на основе логического значения (Boolean-Based Blind SQL Injection) – тип SQL-инъекции, где атакующий не видит прямого вывода SQL-запроса, но может делать выводы на основе логических (истина/ложь) ответов от приложения (эти ответы могут проявляться в виде разных кодов состояния HTTP, разного содержимого ответа или реже разных заголовков).

Анализ ответов позволяет злоумышленникам определить структуру базы данных, а в дальнейшем – буквально символ за символом выяснить, какая информация в ней содержится. Пентестеры и этичные хакеры знают, что это один из самых трудоемких типов атак для ручной эксплуатации. Но несколько простых Python-скриптов помогают полностью автоматизировать процесс:

• Простейший метод – извлекать данные по одному символу, используя функции SUBSTRING() и ASCII() в MySQL. Это позволяет узнавать значение каждого символа в строке путем сравнения с ASCII-кодами.

• Оптимизированный подход – использовать алгоритм бинарного поиска. Это сокращает количество запросов для определения одного символа с 96 до 7, что значительно ускоряет процесс и делает атаку менее заметной.

• Дополнительные приемы для извлечения разных типов данных включают использование подзапросов для выбора данных из произвольных таблиц, объединение значений из нескольких строк в одну строку с помощью GROUP_CONCAT и преобразование разных типов данных (числа, даты и т. д.) в строки, которые легче извлечь.

Для дальнейшего ускорения процесса можно использовать многопоточность с помощью ThreadPoolExecutor из библиотеки concurrent.futures.

📶 Паттерны коммуникации в распределенных системах

Распределенные системы состоят из многих отдельных частей (или узлов), работающих вместе, но физически расположенных в разных местах. Эти части системы должны общаться друг с другом через сеть, чтобы система могла функционировать как единое целое. Хотя коммуникация критически важна, правильно ее организовать бывает непросто: разработчики иногда пытаются использовать один и тот же подход ко всем задачам коммуникации, что может быть неэффективно. Важно понимать, что существуют разные способы организации коммуникации, и выбор правильного метода зависит от конкретной задачи. Рассмотрим основные паттерны коммуникации, которые можно использовать для решения разных задач.

Запрос-ответ с HTTP

Этот синхронный паттерн коммуникации предполагает, что один сервис отправляет запрос другому сервису и ожидает ответа или ошибки, блокируя свою работу до получения результата. REST, наиболее популярный архитектурный стиль для этой модели коммуникации, использует методы протокола HTTP – GET, POST, PUT и DELETE.

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

Общие данные

Этот паттерн часто остается незамеченным, поскольку разработчики не всегда воспринимают его как модель коммуникации. В рамках этого подхода один компонент записывает данные в определенное место, а другой компонент считывает и обрабатывает эти данные. Например, один сервис может загрузить файл в облачное объектное хранилище (например, в корзину Amazon S3), а другой сервис затем извлекает этот файл для дальнейших действий.

Главное преимущество этого паттерна – простота реализации и возможность обеспечения взаимодействия между устаревшими и современными системами без проблем совместимости. Однако он не подходит для сценариев, требующих низкой задержки.

Асинхронный запрос-ответ

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

Основная сложность здесь — корреляция между запросом и ответом: экземпляр сервиса, отправивший запрос, может отличаться от экземпляра, получающего ответ, поэтому требуется способ отслеживания запросов.

Коммуникация на основе событий

В этом подходе сервисы не общаются напрямую друг с другом, а генерируют события, которые могут быть использованы другими сервисами. Это требует наличия места для отправки данных о событиях и механизма, позволяющего получающим сервисам обнаруживать эти события. Брокеры сообщений, такие как RabbitMQ, могут обрабатывать оба этих аспекта. Издатели используют API для отправки событий в брокер, который управляет подписками и уведомляет подписчиков при поступлении события.

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

🛠️ Инструменты

Postgres Sandbox – ИИ-песочница для работы с PostgreSQL в браузере. Проект реализован на PGlite – легковесной версии PostgreSQL, скомпилированной в WebAssembly и упакованной в клиентскую библиотеку TypeScript. Это позволяет запускать базу данных PostgreSQL непосредственно в браузере, Node.js и Bun без необходимости устанавливать другие зависимости. Размер PGLite – всего 3 Мб после сжатия Gzip, при этом база поддерживает многие расширения PostgreSQL, включая pgvector.

textual-plotext – виджет-обертка библиотеки для построения графиков Plotext. Визуализирует данные из Python-скриптов прямо в терминале.

BunkerWeb – опенсорсный веб-фаервол (WAF), созданный на основе NGINX. Предназначен для защиты веб-сервисов – делает их безопасными по умолчанию. Легко интегрируется в существующие среды (Linux, Docker, Swarm, Kubernetes и т. д.), полностью адаптируется под ваши специфические требования. Предоставляет удобный веб-интерфейс и систему плагинов.

Kardinal – фреймворк для создания сверхлегких временных сред разработки внутри общего кластера Kubernetes. Позволяет быстро и эффективно создавать и удалять рабочие пространства для разработки, тестирования и демонстраций, минимизируя затраты ресурсов и стоимость эксплуатации.

Viking – инструмент для управления удаленными серверами (и группами серверов) через SSH.

Terminus – опенсорсная ОС на базе Kubernetes, которая позволяет создать домашнее облако на собственном сервере. Подходит для любых задач – локального хостинга LLM, хаба по управлению IoT-девайсами, персонального репозитория или рабочего пространства.

DeltaDB – легковесная, быстрая и масштабируемая база данных, созданная на основе polars и deltalake. Предназначена для разработчиков и организаций, которым нужно эффективное, простое и гибкое решение для обработки больших объемов данных с высокой скоростью и масштабируемостью.

emval – супербыстрый валидатор email-адресов для Python-приложений, написанный на Rust.

RustPython – интерпретатор Python, написанный на Rust.

Автор рассылки: Наталья Кайда

Ozon Fintech расширяется и набирает новых сотрудников. Чтобы узнать, как живется программистам в этой сфере, мы поговорили с одним из разработчиков компании и попросили рассказать о своем трудовом дне, важных задачах и обо всем, ради чего стоит приезжать в офис (спойлер: там есть даже бар!).

Привет, меня зовут Дмитрий. Я уже четвертый год работаю в Ozon Fintech — это подразделение компании, которое создает новые финансовые продукты. Изначально я пришел на направление банковских карт. Через какое-то время мой руководитель заметил во мне лидерские качества и предложил стать тимлидом. Все получилось, правда, не сразу (но об этом расскажу позже).

Я хорошо помню, как приехал на собеседование. К тому времени я недолго жил в Москве, а в «Москва-Сити» вообще не был ни разу — и тут я попадаю в этот район небоскребов! Сначала подумал, что сейчас зайду в офис, а там мне сразу дадут пачку билетов с сотней вопросов, и если я не отвечу на какой-нибудь 99-й, то провалю собеседование. Но все оказалось проще. На интервью мы в спокойной обстановке обсуждали разные технические вопросы, никаких экзаменов.

Помню, как мы идем по офису на 49-м этаже, а я думаю: «Очень красиво и здорово, конечно, но к окну я пока подходить побаиваюсь».

В первый день показывают рабочее место и выдают ноутбук (у нас можно выбрать «операционку»: Windows, MacOS или Linux). Всем новичкам дарят приветственную коробку с подарками, а по праздникам — мерч компании. Вещи стильные и хорошо сделаны, ими хочется пользоваться.

Когда я только пришел в финтех, в команде проекта нас было немного, человек 20–30. Сейчас там уже под 500 специалистов. Поскольку мы делаем успешные продукты, подразделение растет и нужно больше золота сотрудников. Посмотрите, какие вакансии есть прямо сейчас. Если где-то узнали себя — скорее отправляйте резюме.

• Разработчик Go в группу клиентских сервисов

• Разработчик продуктовых сервисов на Go

• Разработчик финансовых сервисов на Go

• Старший разработчик Go

• Старший разработчик iOS

• QA-инженер

• Инженер по автоматизации тестирования

• Старший инженер по автоматизации тестирования

• Инженер devops

• Маркетинговый аналитик

От кандидатов на позицию разработчика ждут опыта на Golang. Но если вы пишете на другом языке и готовы «пересесть» на Go — так тоже можно. На собеседовании будут оценивать только знания алгоритмов и структур данных, баз данных и архитектуры.

Коробка с подарками — не самое интересное, что встречается сотрудникам в финтехе. Читайте дальше :)

По опыту могу сказать, что первое время работы — самое сложное. Ты только пришел, еще не понимаешь, что делать. А что, если допустишь ошибку? В начале очень нужен наставник, которому ты доверяешь и можешь прийти в любой момент. У нас в финтехе на первом этапе у каждого сотрудника он есть и готов объяснить, что у нас за компания, какие у нее цели и зачем мы все вообще работаем. Потом, конечно, привыкаешь, обживаешься, необходимость в наставнике пропадает.

У нас работают удаленщики из разных уголков страны, но даже местные могут договориться о комфортном режиме посещения офиса. Где-то раз в квартал мы с коллегами собираемся поработать все вместе (сотрудникам из других городов оформляем командировку в Москву, компания оплачивает транспорт и отель), а вечером ходим отдохнуть. А я хоть и живу в Москве, но почти не бываю в офисе. Приезжаю, только если соскучился по коллегам, или вот, например, ради фотографий для поста. Каким бы ни был классным офис, но все же у меня дома два кота, которые будят меня в 5 утра гремящими игрушками.

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

У нас нет фиксированных рабочих часов — каждый выбирает удобное время для себя. Единственное, мы договорились, что с 12 до 17 все должны быть на связи. В остальном на часы никто не смотрит: работу оценивают по результатам.

Дресс-кода тоже нет, даже в офисе. Ну а на удаленную планерку вообще можно заходить хоть из кровати, я и сам так иногда делаю.

Но и тем, кто каждый день ходит в офис, скучать не приходится. У нас есть много всего интересного, но давайте сразу перейдем к главному — к бару! Наши дизайнеры — творческие люди, им хочется и в офис привнести что-то такое. Вот они и решили, что просто опенспейс — это слишком скучно и сухо и нам нужно организовать собственный бар. Он классный и атмосферный: с неоновыми надписями и рядами всяких бутылочек. В рабочее время коктейли, конечно, только безалкогольные.

Кроме бара есть другие «плюшки» от компании, более привычные: ДМС со стоматологией, врач и психолог в офисе, бесплатная йога, скидки на абонементы в фитнес-клубы (для москвичей, а для удаленщиков — сервис «Фитмост») и обеды в соседних заведениях. Все это каждый новый сотрудник получает в начале работы. А еще компания дарит промокоды на Ozon Premium и открывает доступ к особым спецпредложениям и скидкам.

Я люблю баскетбол, и Ozon раз в неделю бронирует зал, чтобы мы могли поиграть. Еще ребята занимаются футболом, волейболом, бегом.

У нас в офисе удобные и безопасные для спины кресла. На вид обычные, но когда кто-нибудь узнает их цену, часто восклицают: «Что? Это же просто черное кресло!» Да, просто кресло, но в нем не болит поясница. Для тех, кому кресло надоело, есть рабочие зоны с диванами и пуфиками.

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

В начале поста я обещал рассказать, почему не сразу стал тимлидом. Так вот. Когда я согласился на эту роль, очень быстро стало понятно, что у меня не получается. Было только представление, что нужно делать, а вот как — непонятно. Ощущения не очень: будто сидишь в лодке посреди океана и не знаешь, куда плыть.

Я попросил о помощи своего руководителя. Он дал советы, помог получить фундаментальные знания по этой теме. Для меня организовали обучение и плавно ввели в новую роль. У нас в целом поощряют и образование, и самообразование: оплачивают нужные курсы и дают доступ к большой онлайн-библиотеке.

После этого у меня стало получаться гораздо лучше. Сейчас я уже начинаю сам помогать другим ребятам становиться руководителями.

Вот так и работает программист в Ozon Fintech. Наше подразделении активно растет, у нас много проектов, интересных задач и челленджей, поэтому нужны светлые головы. Приходите к нам!

ПОСМОТРЕТЬ ВАКАНСИИ

Запрос данных из MongoDBL:

Несмотря на наличие прекрасного стандартного 𝗦𝗤𝗟-пакета, 𝗚𝗼 не поддерживает аналогичный пакет для работы с базами данных 𝗡𝗼𝗦𝗤𝗟. Для этого вам придется использовать сторонние инструменты. Вместо изучения реализации каждого такого стороннего пакета мы сосредоточимся исключительно на 𝗠𝗼𝗻𝗴𝗼𝗗𝗕. Для этого будем применять драйвер 𝗺𝗴𝗼 (произносится «манго»). Начните с установки 𝗺𝗴𝗼:

Теперь можно установить подключение и запросить коллекцию 𝘀𝘁𝗼𝗿𝗲 (эквивалент таблицы), для чего потребуется еще меньше кода, чем в примере с 𝗦𝗤𝗟, который мы создадим чуть позже.

Сначала идет определение типа 𝗧𝗿𝗮𝗻𝘀𝗮𝗰𝘁𝗶𝗼𝗻, который будет представлять один документ из коллекции 𝘀𝘁𝗼𝗿𝗲. Внутренний механизм представления данных в 𝗠𝗼𝗻𝗴𝗼𝗗𝗕 — это двоичный 𝗝𝗦𝗢𝗡. По этой причине для определения любых директив маршалинга используются теги. В этом случае с их помощью мы явно определяем имена элементов для применения в двоичных данных 𝗝𝗦𝗢𝗡.

В функции 𝗺𝗮𝗶𝗻() вызов 𝗺𝗴𝗼.𝗗𝗶𝗮𝗹() создает сессию, устанавливая подключение к базе данных, выполняя тестирование на наличие ошибок и реализуя отложенный вызов для закрытия сессии. После этого с помощью переменной 𝘀𝗲𝘀𝘀𝗶𝗼𝗻 запрашивается база данных 𝘀𝘁𝗼𝗿𝗲, откуда извлекаются все записи коллекции 𝘁𝗿𝗮𝗻𝘀𝗮𝗰𝘁𝗶𝗼𝗻𝘀. Результаты мы сохраняем в срезе 𝗧𝗿𝗮𝗻𝘀𝗮𝗰𝘁𝗶𝗼𝗻 под названием 𝗿𝗲𝘀𝘂𝗹𝘁𝘀. Теги структуры используются для демаршалинга двоичного 𝗝𝗦𝗢𝗡 в определенный нами тип. В завершение выполняется перебор результатов и их вывод на экран. И в этом случае, и в примере с 𝗦𝗤𝗟 из следующего раздела вывод должен выглядеть так:

Обращение к базам данных SQL:

𝗚𝗼 содержит стандартный пакет 𝗱𝗮𝘁𝗮𝗯𝗮𝘀𝗲/𝘀𝗾𝗹, который определяет интерфейс для взаимодействия с базами данных 𝗦𝗤𝗟 и их аналогами. Базовая реализация автоматически включает такую функциональность, как пул подключений и поддержка транзакций. Драйверы базы данных, соответствующие этому интерфейсу, автоматически наследуют эти возможности и, по сути, являются взаимозаменяемыми, поскольку 𝗔𝗣𝗜 между ними остается согласованным. Вызовы функций и реализация в коде идентичны независимо от того, используете вы 𝗣𝗼𝘀𝘁𝗴𝗿𝗲𝘀, 𝗠𝗦𝗦𝗤𝗟, 𝗠𝘆𝗦𝗤𝗟 или другой драйвер. В результате этого удобно менять серверные базы данных при минимальном изменении кода клиента. Конечно же, эти драйверы могут реализовывать специфичные для БД возможности и задействовать различный 𝗦𝗤𝗟-синтаксис, но вызовы функций при этом практически одинаковы. Поэтому мы покажем, как подключать всего одну базу данных 𝗦𝗤𝗟 — 𝗠𝘆𝗦𝗤𝗟, а остальные БД 𝗦𝗤𝗟 оставим в качестве самостоятельного упражнения. Начнем с установки драйвера:

Далее создадим простой клиент, который подключается к этой базе данных и извлекает информацию из таблицы transactions, как показано в коде ниже.

Код начинается с импорта пакета 𝗚𝗼 𝗱𝗮𝘁𝗮𝗯𝗮𝘀𝗲/𝘀𝗾𝗹. Это позволяет реализовать взаимодействие с базой данных через удобный интерфейс стандартной библиотеки 𝗦𝗤𝗟. Кроме того, мы импортируем драйвер базы данных. Начальное подчеркивание указывает на то, что она импортируется анонимно, то есть ее экспортируемые типы не включаются, но драйвер регистрируется пакетом 𝘀𝗾𝗹, и в результате драйвер 𝗠𝘆𝗦𝗤𝗟 сам обрабатывает вызовы функций.

Далее идет вызов 𝘀𝗾𝗹.𝗢𝗽𝗲𝗻() для установки подключения к базе данных. Первый параметр указывает, какой драйвер использовать — в данном случае это 𝗺𝘆𝘀𝗾𝗹, а второй определяет строку подключения. Затем мы обращаемся к базе данных, передавая инструкцию 𝗦𝗤𝗟 для выбора всех строк из таблицы 𝘁𝗿𝗮𝗻𝘀𝗮𝗰𝘁𝗶𝗼𝗻𝘀, после чего перебираем эти строки, последовательно считывая данные в переменные и выводя значения.

Это все, что необходимо для запроса данных из 𝗠𝘆𝗦𝗤𝗟. Для использования другой серверной БД потребуется внести в код лишь минимальные изменения:

• импортировать подходящий драйвер базы данных;

• изменить передаваемые в sql.Open() параметры;

• скорректировать SQL-синтаксис в соответствии с требованиями серверной базы данных.

Среди нескольких доступных драйверов баз данных часть написаны на чистом 𝗚𝗼. А некоторые другие используют 𝗰𝗴𝗼 для ряда внутренних взаимодействий. Полный список доступных драйверов можно найти здесь: 𝗵𝘁𝘁𝗽𝘀://𝗴𝗶𝘁𝗵𝘂𝗯.𝗰𝗼𝗺/𝗴𝗼𝗹𝗮𝗻𝗴/𝗴𝗼/𝘄𝗶𝗸𝗶/𝗦𝗤𝗟𝗗𝗿𝗶𝘃𝗲𝗿𝘀/.

ССЫЛКА НА ТЕЛЕГРАМ КАНАЛ АВТОРА

8) Какую литературу бы посоветовали?

9) Как относитесь к другим языкам, которые решают похожие задачи? В чем преимущества или недостатки Go перед Elixir, Java, C# и далее, например, при написании сервисов? Было бы интересно узнать и о других областях, в которых имела бы место конкуренция этих ЯП.

Всем спасибо за ответы!