Home

Автор: Юлия Багрий

Оригинальная публикация: http://quality-lab.ru/your-api-is-your-public-face/

Для начала нам нужно понять, что же такое API?
API (Application Programming Interface) – это интерфейс, который позволяет осуществлять взаимодействие между программами. Если человек общается с приложением через кнопки и диалоги (пользовательский интерфейс, UI), то программы обмениваются информацией друг с другом через API.

Категории взаимодействия API

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

• мобильное либо десктопное приложение синхронизирует данные с сервером;
• приложение использует вычислительные возможности сервера (к примеру, приложение Prism загружает фото и информацию о выбранном стиле на сервер, где уже происходит стилизация изображения);
• взаимодействие между веб-приложением и сервером;
• взаимодействие между микросервисами.

Основные риски, связанные с внутренним API, – это функциональные дефекты и проблемы производительности. Здесь пользователи могут лишь предполагать, из-за чего конкретно приложение работает «как-то не так».

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

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

Действительно, если в публичный доступ выходит API с плохой документацией, путаницей в версионности и кучей функциональных проблем, то внешние разработчики могут (да просто обязаны!) предположить, что точно так же (а то и хуже) разработана вся система. Будут ли они строить сторонние сервисы вокруг такой системы, привлекая новых клиентов? Конечно, нет. Отговорят ли своих начальников и друзей от использования или покупки? Наверняка, да. И не нужно забывать, что для далеких от технических вопросов людей мнение разработчика будет решающим. А еще они обязательно пожалуются на ваш сервис в социалках или форумах, оттолкнув немало потенциальных пользователей. Следовательно, перед публикацией любого, пусть даже самого крохотного API необходимо позаботиться о его безупречности.

4 способа зафакапить внешний API

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

1. Нерабочая функциональность.
Как это ни банально звучит, сервис должен работать. Более того, он должен выполнять те функции, ради которых создавался. Как-то раз на проекте, где я работала, случился конфуз с операцией экспорта. Мы протестировали работу API на различных объектах и условиях, но при этом каждый раз экспортировали только один объект. Все шло хорошо до тех пор, пока при экспорте большого числа объектов вдруг не обнаружилась ошибка. Сама операция задумывалась с целью предоставить возможность массовой выгрузки – а следовательно, поставленная задача не была решена.

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

Другая проблема: учитываете ли вы при разработке сервиса основной регион, где его будут использовать? Понятно, что для австралийцев поддержка русских кодировок не так важна. Но уж если вы работаете со странами СНГ, то проверить все нюансы работы с кириллицей просто необходимо. По своему опыту скажу, что даже при всеобщем проникновении Unicode до сих пор можно встретить банальную ситуацию: пользователь загрузил файл с именем «Документ_1.pdf», а на выходе получил уже обрезанный «_1.pdf».

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

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

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

Зададимся следующим вопросом: как именно разработчики узнают о проблемах в работе сервиса? Появляется ли специальное сообщение о временных неполадках или инфраструктурных работах? Даются ли примерные сроки завершения работ? Часто для таких случаев используются специальные страницы, на которых публикуется информация о глобальных проблемах и сроках их решения.

Если вы поставляете пользователям несколько отдельных сервисов, то их доступность удобно представить в виде сводной таблицы по статусам.

Нажмите на картинку, чтобы увеличить изображение

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

3. «Кривое» юзабилити.

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

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

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

"Поставьте разрабам Пунтосвич. На этот раз в схеме в элементе Centralized первая буква русская."

"У ваших разрабов в кровь поступает слишком много алкоголя, и их внимательность резко падает. В схеме при написании элемента в его имени была допущена эпическая ошибка – Рressure было написано с первым символом русского языка и получилось: эрRessure."

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

• У вас есть пользовательский интерфейс и API? Не забывайте проверять их на адекватность друг к другу («любимая» проблема – это несоответствие полей. Например, на UI в поле можно ввести 50 символов, а в схеме API – ограничение на 20 символов. При попытке экспортировать данные, созданные на UI, срабатывает ошибка валидации схемы).
• Не забывайте о продуманной и поддерживаемой версионности (как в самом API, так и в его документации). Чем старше ваш сервис, тем бережнее нужно относится к изменениям, которые ломают совместимость. Документация всегда должна быть актуальной – это всем известная прописная истина. Но случаются курьезы, при которых ее публикуют «впереди паровоза» (например, актуальный API версии 11.0 вдруг снабжается мануалом версии 11.1: разработчики пытаются использовать возможности новой версии, не находят их и пишут, что у вас «опять всё сломано»).
• Очень неприятно встречаться с ситуацией, когда клиентов лишь постфактум уведомляют об изменениях в принципах работы с системой. Пользователей нужно готовить к новшествам, иначе о вашем стиле работы может сложиться такое мнение:

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

4. Дыры в безопасности.
Выпуская API в публичный доступ, вы всегда увеличиваете потенциальную поверхность атаки для злоумышленников. Прежде всего, это сам процесс авторизации и аутентификации. Для доступа к API чаще всего используют специальные ключи доступа (access token). Возможно, вам хватит простого ключа разработчика, который он получит при регистрации своего приложения в вашем сервисе. Могут понадобиться дополнительные ключи доступа для идентификации конкретного пользователя, воспользовавшегося приложением от стороннего разработчика. Такие ключи чаще всего генерируют с помощью протокола OAuth. Возможно, передаваемая информация настолько критична, что вам потребуется подпись запросов.

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

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

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

Заключение

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

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

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

Обсудить в форуме.