Проектирование API *

Нередко при работе с Bitrix24 REST API возникает необходимость быстро получить содержимое определенных полей всех элементов какого-то списка (например, лидов).

Традиционный способ для этого - обращение к серверу через метод *.list (например, crm.lead.list для лидов) с параметром select, перечисляющим список требуемых полей. При этом, чем больше полей вы запрашиваете, тем больше времени серверу требуется для формирования ответа. Плюс, в силу того, что информация сервером выдается постранично, получение всего списка через последовательные запросы всех страниц может занимать много времени.

Однако существует несколько стратегий для того, которые позволяют ускорить процесс на порядки.

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

C API все так же распространены, как и раньше. На C написано много библиотек или библиотек с предоставлением C API. Есть также биндинги для различных языков программирования, что делает язык C стандартом де-факто для переносимых API. Тем не менее многие API не соответствуют базовым принципам проектирования, и, похоже, что за последние годы в этой области мало чего изменилось. Недавно мне пришлось поработать над современным C API, но затем появился Vulkan с несколькими интересными идеями. Самое время взглянуть на современные варианты разработки C API.

Недавно я пересматривал Назад в Будущее, культовую трилогию о том, как парень со своим гениальным дедом путешествует в будущее, прошлое и обратно. Интересно видеть, как почти 30 лет назад люди видели будущее- ховерборды вместо скейтов, летающие автомобили, романтика!

Используйте глобально уникальные идентификаторы. Клиент всегда должен знать полное состояние системы. Избегайте двойных отрицаний…

Полгода назад, летом 2020 года я написал скрипт поиска ликвидных облигаций на Мосбирже (статья в закладках у 194 человек, рейтинг +45). Скрипт нужен для поиска облигаций, которые можно купить прямо сейчас с доходностью гораздо выше банковского вклада.

Сейчас, в начале 2021 года модифицировал прошлогодний скрипт, потому что проценты по вкладам так и остаются на очень низких уровнях, а с началом 2021 года ещё и изменения в налоговом кодексе РФ подоспели. 

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

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

Для тех же, кому уже захотелось ознакомиться с Botsman (но не очень хочется много читать) — вот ссылка, милости прошу: https://bots.mn/. Главное, о чём стоит помнить — платформа только-только запустилась, и (пока что) не стоит переносить на неё что-то серьёзное и масштабное.

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

1. Предоставляйте минимальный объём функциональности

В любой момент времени ваше API подобно айсбергу: у него есть видимая (документированная) часть и невидимая — недокументированная. В хорошем API эти две части соотносятся друг с другом примерно как надводная и подводная часть настоящего айсберга, 1 к 10. Почему так? Из двух очевидных соображений.

Технология IP-геолокации существует уже давно. Это единственный ненавязчивый инструмент, который поставщик услуг может использовать для оценки географического положения онлайн-посетителей.

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

Но насколько точна IP-геолокация? Можем ли мы доверить ей принятие важных бизнес-решений?

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

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

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

Целью этой статьи не является сравнение различных провайдеров геолокации IP. Но это будет скоро, следите за обновлениями!

В этой статье рассматриваются основы IP-геолокации, а затем объясняется наилучшая точность и результаты, которые мы теоретически можем ожидать от «идеальной» IP-геолокации. Затем в ней описываются концептуальные ограничения, о которых мы должны знать, и в какой степени мы можем доверять получаемым данным.

IPv4 - это надолго

Когда мы говорим о геолокации IP, мы в первую очередь рассматриваем адресное пространство IPv4, так как большая часть нашего веб-трафика все еще идет с адресов IPv4.

IPv6 был создан, чтобы решить глобальную нехватку адресного пространства IPv4, предоставив колоссальное расширение аж на 2128 адресов. Однако этого не произошло, хотя с момента его введения прошло два десятилетия.

Что случилось?

Как обычно, дадим смысловой определение «обратной совместимости», прежде чем начинать изложение.

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

Ситуацию с использованием кодов ответов HTTP можно заносить в палату мер и весов: вот что происходит, когда благие намерения разработчиков спецификации сталкиваются с жестокой реальностью. Даже с двумя жестокими реальностями.

Как мы обсудили в Главе 10, одна из целей существования семантических ошибок — помочь клиенту понять, что стало причиной ошибки. При разработке спецификации HTTP (в частности, RFC 7231) эта цель очевидно была одной из главных. Более того, архитектурные ограничения REST, как их описал Фьелдинг в своей диссертации, предполагают, что не только клиенты должны понимать семантику ошибки, но и все сетевые агенты (прокси) между клиентом и сервером в «многослойной» архитектуре. И, в соответствии с этим, номенклатура статус-кодов HTTP действительно весьма подробно описывает почти любые проблемы, которые могут случиться с HTTP-запросом: недопустимые значения Accept-*-заголовков, отсутствующий Content-Length, неподдерживаемый HTTP-метод, слишком длинный URI и так далее.

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

События (Events) предлагают подход в стиле принципа Златовласки, в котором API реального времени (real-time APIs) могут использоваться в качестве основы для приложений, которые являются гибкими, но в то же время высокопроизводительными; слабосвязанными, но эффективными.

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