API - это первый и самый важный способ доступа разработчиков к вашим продуктам и взаимодействия с ними. Сама Adobe движется к тому, чтобы стать платформой, ориентированной на API, и Клаасьян Туккер, директор по управлению продуктами Adobe Cloud Platform, только что дал нам эксклюзивное представление о передовых методах создания хороших API и правильной расширяемости.
Мы хотели знать, что другие эксперты по API считают наиболее важными функциями, о которых следует думать при создании API, поэтому мы поговорили с тремя ведущими консультантами и одним старшим инженером, который имеет практический опыт тестирования новых API. Следуйте их советам, чтобы поддерживать ваш API и работать с ним приятно.
Хороший API знает своего реального пользователя
Мои пальцы застыли на клавиатуре, а мои мысли постепенно переходили из состояния замешательства в изумление. Я создавал прототип интеграции с API, который взаимодействует с контактами: именами, адресами электронной почты и другими личными данными. Моя интеграция потребовала, чтобы я перечислил самые последние контакты в системе. Просматривая документы, я наконец понял, что это сбивает меня с толку; этот API не поддерживает мой вариант использования.
Когда вы думаете о том, что кто-то использует API, вы, скорее всего, представляете, как разработчик пишет код. Тем не менее, этот разработчик выполняет работу от имени людей, которые в конечном итоге будут использовать программное обеспечение. Код может вызывать конечную точку API, но пользователь видит, как код интерпретирует результат.
В моей интеграции API контактов пользователи запрашивали самые свежие контакты. Чтобы соответствовать ожидаемому варианту использования, мне пришлось пролистать все контакты - их могло быть тысячи - и отслеживать дату и время добавления каждого из них. Несмотря на то, что API был способен выполнять все операции CRUD, потребовались значительные усилия, чтобы приспособить его к очень распространенному варианту использования. Простой вариант сортировки сделал бы его одним вызовом API. Более того, API мог бы поддерживать веб-перехватчики и отправлять моему приложению новые контакты, когда каждый из них становится доступным.
Хороший API продумывает свой опыт разработчика, предоставляя полную, точную и легко усваиваемую документацию. Он также помогает своим разработчикам, продумывая распространенные варианты использования, которые могут понадобиться настоящему пользователю API.
~ Адам ДюВандер, консультант по коммуникациям разработчиков
Хороший API отлично обрабатывает ошибки
При написании HTTP API вы должны оптимизировать работу с разработчиком. Молва имеет значение, и если разработчики, использующие ваш API, могут сделать это легко, они порекомендуют его. Область API, которая жизненно важна для хорошего взаимодействия с разработчиком, о которой часто забывают, - это обработка ошибок: сделайте это правильно для своего API.
Убедитесь, что вы используете правильный код состояния (4xx или 5xx для ошибки). Никогда не используйте 200 со свойством error в вашем теле, так как вы рискуете, что он будет кэширован прокси. Используйте код 4xx, если клиент должен что-то сделать перед повторной попыткой, и код 5xx в противном случае. В ответе об ошибке должен быть указан код ошибки конкретного приложения, чтобы клиент мог выполнять различные действия в зависимости от того, что произошло. Однако вам также потребуется удобочитаемое сообщение, чтобы как можно больше помочь разработчику, чтобы они могли решить проблему. Я рекомендую вам использовать стандартный формат ответа для вашей ошибки, такой как RFC 7807 Problem Details for HTTP APIs, и существуют библиотеки, которые будут его декодировать.
Плохая реакция на ошибку может отпугнуть разработчиков и заставить их отказаться от вашего API. Создайте отличный, и разработчики ваших клиентов будут вам благодарны!
~ Роб Аллен, консультант и разработчик API, 19FT
Хороший API бережно относится к новичкам и дает возможность опытным пользователям.
Документировано. Необходимость угадывать, как использовать API, из-за отсутствия документации крайне разочаровывает. Это не обязательно должен быть 1000-страничный фолиант; вводного абзаца, в котором объясняется, что делает API и для кого он предназначен, а также простых фрагментов, демонстрирующих, как использовать каждый метод, будет достаточно в 90% случаев. Бонусные баллы за автономные рабочие примеры, чтобы быстро начать работу.
Предсказуемость и последовательность. Последовательный, хороший нейминг; единообразие и отсутствие неожиданностей - все это помогает войти в поток, так что разработчики только изредка останавливаются, чтобы кратко проверить документацию - если они действительно должны, потому что хорошие API-интерфейсы настолько интуитивно понятны, что угадывать часто быстрее, чем обращаться к документации.
Легко взаимодействовать с другим кодом. Побочным эффектом согласованности является легкость взаимодействия с существующим и будущим кодом. Например, если весь ваш API основан на обратном вызове, очень просто использовать библиотеки, такие как promisify, чтобы превратить ваш API в основанный на обещаниях, если все методы используют одну и ту же сигнатуру.
Хорошие сообщения об ошибках. Несмотря на все усилия разработчика API, иногда все идет не так, как ожидалось. Тогда API, который указывает разработчикам на нужное место с помощью мягкой информативной ошибки, стоит в 1000 раз больше, чем API, который выдаёт загадочное сообщение об ошибке и дает сбой.
~ Соледад Пенадес, менеджер по разработке DevTools в Mozilla
Хороший API - это намеренный контракт
Когда вы публикуете API, вы заключаете явный контракт со своими клиентами, потребителями вашего API. После того, как вы заключили такой контракт, любые дополнения или изменения должны поддерживать обратную совместимость. Однако поддержание обратной совместимости может быть проблематичным, если API намеренно не создается для поддерживаемых им вариантов использования.
При разработке намеренно созданного API четкое разделение является ключевым моментом. Важно четко отделить ваши внутренние модели объектных данных (включая любые реализации) от объектных схем, представленных в вашей спецификации API, чтобы избежать тесной связи. Внесение будущих изменений в реализацию тесно связанного API с самого начала приведет к увеличению технического долга за счет введения слоя ненужной сложности для поддержания этого контракта API.
Например, реструктуризация ваших моделей данных или замена внутренних реализаций потенциально потребует сосредоточения внимания на поддержании перевода от вашей целевой модели к модели данных, которая больше не используется и не согласована с тем, что действительно требовалось с самого начала. Кроме того, важно убедиться, что ваши схемы открытых объектов минималистичны и содержат только те элементы, которые необходимы для поддерживаемых вариантов использования. Лучше избегать ярлыков, таких как раскрытие объекта целиком в том виде, в котором он существует сегодня внутри компании. Свойства объекта, несущественные для ваших вариантов использования, могут привести к тому, что клиенты будут полагаться на ваш API как в непреднамеренных, так и в неподдерживаемых вариантах использования.
~ Энди Стид, старший компьютерный инженер, опыт работы с моделями данных, Adobe
Хороший API означает понимание
API - это связь между мирами. С одной стороны это вы, с другой - миры ваших клиентов. Более десяти лет я был наставником как стартапов, так и предприятий и заметил, что у лучших API есть четыре общих черты: понимание сценария использования, понимание технических возможностей, отличное качество связи и сильная долгосрочная приверженность.
Отличные API-интерфейсы заботятся о пользователях. Ключ к успеху - создать API, ориентированный на варианты использования, а не на бизнес-возможности. Создавайте API с учетом действий, которые он предоставляет, а не доступных ресурсов. Часто я вижу, как поставщики API используют ярлыки в надежде, что используемая ими технология поможет избежать понимания того, какие данные или действия нужны пользователю. Однако при отличном дизайне API вы не избежите понимания сценариев использования.
Во-вторых, как архитектор API, вы должны полностью понимать общие парадигмы API (REST, HTTP, RPC – gRPC, Query – GraphQL, Real-time, передача файлов и т. Д.) И выбирать подходящую для конкретного случая использования API и аудитории. . Не позволяйте модным парадигмам и технологиям определять ваши суждения. Правильный стиль API зависит от варианта использования и аудитории.
Публикуя API, вы не только даете обещание сохранить его в рабочем состоянии. Вы также несете ответственность за объяснение этого пользователям. То, насколько вы заботитесь о ясности и качестве коммуникации, влияет на принятие API, запросы в службу поддержки и удовлетворенность клиентов.
Наконец, лучшие API созданы, чтобы работать долго. Сегодня создать, развернуть и масштабировать сервис дешево и просто. Что нет ничего проще, так это создание и поддержка программного обеспечения, которое прослужит десятилетия и при этом может развиваться.
~ Зденек Зи Немец, основатель Good API
Следите за блогом Adobe Tech Blog, чтобы получить больше историй и ресурсов для разработчиков, и посетите Adobe I / O в Твиттере, чтобы узнать о последних новостях и продуктах для разработчиков.
