Api

Избегайте двойных отрицаний

Плохо: — люди в целом плохо считывают двойные отрицания. Это провоцирует ошибки.

Лучше: или — читается лучше, хотя обольщаться все равно не следует. Насколько это возможно откажитесь от семантически двойных отрицаний, даже если вы придумали «негативное» слово без явной приставки «не».

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

Условие «кофе можно приготовить» будет выглядеть как — есть и зерно, и стакан. Однако, если по какой-то причине в ответе будут отрицания тех же флагов:

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

Дизайн в три колонки

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

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

Многие API смоделировали свой дизайн после Stripe. Например, Slate, Spectacle или Readme.io. Следует ли использовать Дизайн в три колонки с документацией по API? Может быть.

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

MYOB Developer Center использует интересный подход к документированию JSON в своих API. Они перечисляют структуру JSON в виде таблицы, с разными уровнями отступов. Можно навести курсор мыши на поле с для появления всплывающей подсказки с описанием или щелкнуть по полю, чтобы раскрыть описание ниже. Использование всплывающих подсказок позволяет идеально выровнять строки, содержащие пример и описание.

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

Избегайте частичных обновлений

Плохо:

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

Во-первых, экономия объёма ответа в современных условиях требуется редко. Максимальные размеры сетевых пакетов (MTU, Maximum Transmission Unit) в настоящее время составляют более килобайта; пытаться экономить на размере ответа, пока он не превышает килобайт — попросту бессмысленная трата времени.

Перерасход трафика возникает, если:

• не предусмотрен постраничный перебор данных;

• не предусмотрены ограничения на размер значений полей;

• передаются бинарные данные (графика, аудио, видео и т.д.).

Во всех трёх случаях передача части полей в лучше случае замаскирует проблему, но не решит. Более оправдан следующий подход:

• для «тяжёлых» данных сделать отдельные эндпойнты;

• ввести пагинацию и лимитирование значений полей;

• на всём остальном не пытаться экономить.

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

В-третьих, этот подход может как-то работать при необходимость перезаписать поле. Но что делать, если поле требуется сбросить к значению по умолчанию? Например, как удалить ?

Часто в таких случаях прибегают к специальным значениям, которые означают удаление поля, например, null. Но, как мы разобрали выше, это плохая практика. Другой вариант — запрет необязательных полей, но это существенно усложняет дальнейшее развитие API.

Хорошо: можно применить одну из двух стратегий.

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

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

Вариант 2: разработать формат описания атомарных изменений.

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

Уродливый API

Из песочницы

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

При разработке фронтенд приложений (mobile/web), часто сталкиваешься с тем, что API на бэкенде еще не реализован. Приходится ждать разработчика на бэкенде, когда он предоставит нужные запросы, постоянно напоминая ему о себе. Не редкость и другая ситуация, когда нужные http запросы уже есть, но они реализованы очень плохо и криво.

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

В этом проекте я разрабатываю мобильное приложение на Flutter, используя пакет Retrofit, который помогает мне сократить время и код, который приходится писать самому, генерируя значительный код автоматически. Так же использую Insomnia, для первоначальной проверки запросов до реализации их в коде.

Итак, начнем.

API операционных систем. Проблемы, связанные с многообразием API

Практически все операционные системы (Unix, Windows, MacOS, и т. д.) имеют API, с помощью которого программисты могут создавать приложения для этой операционной системы.
Главный API операционных систем — это множество системных вызовов.

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

С другой стороны, отличия в API различных операционных систем существенно затрудняют перенос приложений между платформами. Существуют различные методы обхода этой сложности — написание «промежуточных» API (API графических интерфейсов Qt, Gtk, и т. п.), написание библиотек, которые отображают системные вызовы одной ОС в системные вызовы другой ОС (такие среды исполнения, как Wine, cygwin, и т. п.), введение стандартов кодирования в языках программирования (например, стандартная библиотека [[Си языка C), написания интерпретируемых языков, реализуемых на разных платформах (sh, perl, php, tcl, Java, и т. д.)

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

Например: для того, чтобы увидеть в браузере строчку «Hello, world!» достаточно лишь создать HTML-документ с минимальным заголовком, и простейшим телом, содержащим данную строку. Что произойдёт, когда браузер откроет этот документ? Программа-браузер передаст имя файла (или уже открытый дескриптор файла) библиотеке, обрабатывающей HTML-документы, та, в свою очередь, при помощи API операционной системы прочитает этот файл, и разберётся в его устройстве, повызывает через API библиотеки стандартных графических примитивов операции типа «очистить окошко», «написать выбранным шрифтом Hello, world!», при этих операциях библиотека графических примитивов обратится к библиотеке оконного интерфейса с соответствующими запросами, уже эта библиотека обратится к API операционной системы с запросами вида «а положи-ка мне в буфер видеокарты вот это».

При этом практически на каждом из уровней реально существует несколько возможных альтернативных API. Например: мы могли бы писать исходный документ не на HTML, а на LaTeX, для отображения могли бы использовать любой браузер. Различные браузеры, вообще говоря, используют различные HTML-библиотеки, и, кроме того, всё это может быть (вообще говоря) собрано с использованием различных библиотек примитивов и на различных операционных системах.

Основными сложностями существующих многоуровневых систем API, таким образом, являются:

• Сложность портирования программного кода с одной системы API на другую (например, при смене ОС);
• Потеря функциональности при переходе с более низкого уровня на более высокий. Грубо говоря, каждый «слой» API создаётся для облегчения выполнения некоторого стандартного набора операций. Но при этом реально затрудняется, либо становится принципиально невозможным выполнение некоторых других операций, которые предоставляет более низкий уровень API.

Параметризация запросов, переменные окружения

У нас есть коллекция запросов, и мы хотим использовать их на разных окружениях. Допустим, выполнять их локально, на тестовом стенде и на проде. Посмотрим, что предлагает Postman, и как это работает.

В меню создания выбираем Environment 

В ранее созданном запросе выделим в переменные два параметра — URL стенда, к которому мы обращаемся, и токен для авторизации. Назовём наше окружение Test Environment. Создаём две переменные url и token и укажем их значения. На скриншоте ниже их значения скрыты из соображений безопасности.

Сохраняем созданное окружение кнопкой Add. Мы всегда сможем вернуться и отредактировать окружение с помощью кнопки Manage Environments (шестерёнка в правом верхнем углу основного экрана).

Устанавливаем Test Environment в качестве текущего окружения: выбираем из выпадающего списка и вносим параметры в запрос. Переменные указываются в двух фигурных скобках. Postman подсказывает названия переменных окружения при вводе.

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

Запрос вновь прошёл успешно, значит, всё сделали правильно.

Теперь создадим другое окружение, с другими URL и token, и поменяем их с помощью переключения в выпадающем списке. Протестируем продукт на двух разных окружениях, используя одну коллекцию запросов.

Как работает API?

Теперь, когда мы установили, что API — это набор процедур, которые указывают программное обеспечение в правильном направлении, как именно это все работает?

Лучший способ объяснить основные функциональные возможности API — это привести пример из реальной жизни. Службы доставки еды, такие как GrubHub , сейчас невероятно популярны, поэтому давайте обсудим, как может работать код таких мобильных приложений.

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

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

API — это связь между этой базой данных и веб-сайтом или приложением, которое представляет свои данные

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

Например, для веб-сайта было бы полезно, если бы сторонние агрегаторы могли перечислять и организовывать все доступные ему рестораны и предметы, верно? Без API это было бы невозможно без использования неэффективных методов очистки веб-страниц.

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

Что такое REST API?

Representable State Transfer(REST) Application Programming Interface(API) предоставляет набор методов, которые программист может использовать через HTTP для отправки и получения данных. Поскольку эти методы используют HTTP, любой язык программирования может работать с ними.

Сейчас доступны тысячи REST API практически на всех возможных сайтах. Обычно для общедоступных данных, таких как погода или фондовые рынки, вы можете найти десятки разных API, доступных для использования. Многие популярные веб-платформы, такие как Facebook и Twitter, также предоставляют API для разработчиков. Некоторые из проприетарных API имеют ограничения на количество обращений к ним. Многие требуют регистрации и получения закрытого ключа. Наиболее безопасные API требуют настройки OAuth для безопасного входа пользователей.

Вы можете найти огромный список публичных API на Github, а еще больший список существует на RapidAPI.

Плюсы и минусы работы с API

Плюсов у использования API немало:

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

Но также есть и минусы:

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

Запросы на разных языках

Как было сказано ранее в разделе Что такое REST API? REST API не зависит от языка. Универсальный протокол помогает облегчить широкое распространение для разных языков программирования. Разработчики могут кодировать свои приложения на любом языке, от Java до Ruby, JavaScript, Python, C #, Node JS или каком-либо еще. Пока разработчики могут отправлять HTTP-запросы на своем языке, они могут использовать API. Ответ от веб-запроса будет содержать данные в формате JSON или XML.

Поскольку невозможно знать, на каком языке будут писать конечные пользователи, попытка предоставить примеры кода на каждом языке бесполезна. Многие API просто показывают формат для отправки запросов и пример ответа, и авторы предполагают, что разработчики будут знать, как отправлять HTTP-запросы на своем конкретном языке программирования.

Однако некоторые API отображают простые запросы на разных языках. Вот пример из Twilio:

в выпадающем списке можно выбрать, какой язык использовать для примера запроса: C #, curl, Java, Node.js, PHP, Python или Ruby.

Вот еще пример API от Clearbit:

Можно увидеть запрос в Shell (curl), Ruby, Node или Python. Разработчики могут легко скопировать необходимый код в свои приложения, вместо того чтобы выяснить, как заставить запрос curl перевести на определенный язык программирования.

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

Но нас не испугает этот шведский стол с примерами кода. Некоторые инструментальные средства API (такие как или SwaggerHub) могут автоматически генерировать эти примеры кода, поскольку паттерны выполнения запросов REST на разных языках программирования следуют общему шаблону.

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

Как сгруппировать несколько конечных точек одного ресурса

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

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

Предположим, у нас есть три конечных точки GET и одна конечная точка POST, причем все они относятся к одному и тому же ресурсу. На некоторых сайтах документации все конечные точки для одного и того же ресурса могут перечисляться на одной странице. На других сайтах может встречаться разбивка методов на отдельных страницах. На третьих могут быть созданы одна группа для конечных точек GET, а другая — для конечных точек POST. Это зависит от того, что и сколько должно быть сказано о каждой конечной точке.

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

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

15 тривиальных фактов о правильной работе с протоколом HTTP

Внимание! Реклама! Пост оплачен Капитаном Очевидность!
Ниже под катом вы найдёте 15 пунктов, описывающих правильную организацию ресурсов, доступных по протоколу HTTP — веб-сайтов, «ручек» бэкенда, API и прочая. «Правильный» здесь означает «соответствующий рекомендациям и спецификациям»

Большая часть ниженаписанного почти дословно переведена из официальных стандартов, рекомендаций и best practices от IETF и W3C.
Вы не найдёте здесь абсолютно ничего неочевидного. Нет, серьёзно, каждый веб-разработчик теоретически эти 15 пунктов должен освоить где-то в районе junior developer-а и/или второго-третьего курса университета.
Однако на практике оказывается, что великое множество веб-разработчиков эти азы таки не усвоило. Читаешь документацию к иным API и рыдаешь. Уверен, что каждый читатель таки найдёт в этом списке что-то новое для себя.

Популярные API

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

• Facebook API позволяет логиниться на сторонних платформах с помощью своего аккаунта, оплачивать покупки в приложении, получать доступ к данным крупных и средних аккаунтов Instagram Business, управлять страницами сообществ и публиковать на них контент, получать статистику по рекламе, управлять объявлениями и аудиторией, запускать прямые эфиры,
• С помощью Twitter API можно показывать ленту твитов на сайте, управлять профилем и настройками учетной записи, автоматически создавать рекламные кампании в Твиттере и управлять ими,
• API ВКонтакте дает возможность отслеживать активность пользователей в сообществах, создавать ботов, собирать статистику по действиям в сообществе, автоматически модерировать контент, автоматизировать работу с товарами (например, импорт из внешней базы), получать текстовые публикации из ВКонтакте по заданным ключевым словам и т.д.,
• Telegram Bot API представляет собой HTTP-интерфейс для работы с ботами в Telegram,
• YouTube API позволяет встраивать видео на сайт, создавать плейлисты, встраивать плеер в приложение, получать данные об активности пользователей.

Не менее популярны и следующие API:

Яндекс API – у всех популярных сервисов Яндекса есть свои API (Вебмастер, Метрика, Директ, Маркет, Аудитории, Карты и т.д.), благодаря которым можно:

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

Google API

• Работа с устройствами и приложениями на платформе Android,
• Управление событиями в Календаре,
• Управление товарами и акккаунтом в Google Покупках,
• Управление файлами на Google Диске, включая загрузку, скачивание, поиск, изменение прав доступа,
• Просмотр и управление данными Google Analytics,
• Чтение и редактирование файлов в Документах,

API7:2019 Security Misconfiguration (Некорректная настройка параметров безопасности)

• Используются дефолтные настройки приложений, которые могут быть небезопасны.
• Используются открытые хранилища данных.
• В OpenSourсe попала закрытая информация, например, конфигурация системы или параметры доступа.
• Неправильно сконфигурированы HTTP заголовки (данная тема рассмотрена далее в разделе «Insecure HTTP Headers»).
• Аутентификационные данные (логин/пароль, токен, apiKey) посылаются в URL. Это небезопасно, т.к. параметры из URL могут оставаться в логах веб серверов.
• Отсутствует или неправильно используется политика Cross-Origin Resource Sharing (CORS) (данная политика рассмотрена далее в одноимённом разделе).
• Не используется HTTPS (использование HTTPS рассмотрено в разделе «Insecure Transport»).
• При эксплуатации промышленной системы используются настройки, предназначенные для разработки и отладки.
• Сообщения об ошибках содержат чувствительную информацию, например, трейсы стека.

• Для пользователей устанавливать только необходимые права доступа.
• Открывать только необходимые сетевые порты.
• Устанавливать безопасные версии патчей OS и приложений (подробно рекомендации рассмотрены в разделе «Using Components with Known Vulnerabilities»).