Представим, что вы работаете над веб-проектом с группой людей, это могут быть ваши друзья, товарищи по команде или даже родственники, в любом случае вы собираетесь работать вместе, что означает распределение работы (в идеале). Чтобы дать немного больше ограничений, каждый член команды действительно хорош в своей основной области работы, будь то фронтенд, бэкэнд, UI / UX, но не все в одном.
Чтобы сделать его более реалистичным, предположим, что это веб-приложение для обмена самописными сообщениями в блоге с другими пользователями приложения. Лучшее название, которое я придумал для этой миллионной идеи, - WellDone.
Когда самая сложная часть проекта сделана (выбор имени), нам нужно подумать о данных, которые мы собираемся создавать и извлекать, поскольку это сердце практически любого приложения. Обычно эти проблемы можно решить с помощью API, поскольку это относительно простой способ описания ресурсов данных и действий, которые могут быть выполнены с ними.
Попытка WellDone №1
После нескольких часов обсуждения команда решила создать API, и он был описан как:
Да, он простой, небезопасный, с проблемами производительности, но он охватывает основные функции, и это именно то, что нам нужно.
Итак, ваш коллега по серверной части проверил требования API и реализовал их за несколько часов, в то время как интерфейсный разработчик все еще настраивал Webpack и проверял, какой фреймворк лучше всего изучать в 2019 году.
Наконец, передняя часть была закончена, и обе части были объединены вместе. Ура?
Не совсем, внезапно пользователи начали получать некоторые нечитаемые человеком ошибки при создании нового сообщения. Кроме того, они хотели указать имя автора, что означает:
- Нам нужно исправить как серверную часть, так и интерфейсную часть, чтобы отправлять и отображать удобочитаемые ошибки.
- Расширить существующий API новыми функциями
После этих изменений API выглядит так:
Итак, это было реализовано и развернуто. Уже ура?
Еще нет, пользователи все еще жалуются, хотя ошибка исчезает, когда пользователь создает новое сообщение в блоге, сообщение по-прежнему не является списком, и весь введенный текст исчезает.
Вопрос в том, почему? Причина в том, что в случае сбоя API отвечает статусом 200 (поскольку это не было согласовано, почему бы и нет?), А тело с сообщением и флагом успеха равно false, что полностью соответствует спецификации API. Между тем, клиент веб-приложения (интерфейс) ожидает получить 400 (неверный запрос) или, возможно, 500 (внутренняя ошибка сервера) в случае ошибки и отобразить сообщение из тела ответа.
Полученные результаты
Хотя мы создали API по согласованной спецификации, которая кажется ясной и простой, мы не полностью удовлетворили потребности нашего продукта. Спецификация API не говорила, какой статус ответа следует ожидать в случае успеха или неудачи, что вызвало недопонимание между сторонами и, как следствие, ужасное взаимодействие с пользователем.
Да, можно описать API более конкретно, чтобы ни у кого не возникло вопросов, но вам все равно нужно подумать о формате, который вы собираетесь использовать, чтобы описать все недостающие детали (и все возможные детали в будущем) кроме того, существует узкое место, поскольку клиент веб-приложения не может попробовать последнюю версию API, пока она не будет реализована, поэтому параллельная работа не выполняется (что заставляет интерфейсных разработчиков писать новые фреймворки в ожидании API, и иногда это не дает хороших результатов).
Если вы спрашиваете, есть ли решение для описания API каким-либо стандартным способом, чтобы каждый мог его понять и спасти мир от фреймворков JavaScript, сразу же используя его без реальной реализации, ответ будет да , он существует!
WellDone попытка # 2
Прежде, чем мы начнем
Группа людей, у которых были такие же проблемы с описанием API, решила сказать хватит, и в результате мы получили Swagger и API Blueprint от Apiary (и, возможно, что-то еще с похожей идеей).
Оба продукта великолепны, но похоже, что с проекта API легче начать (я думаю, из-за простого текстового формата по сравнению с JSON / YAML), поэтому я продолжу.
API Blueprint прост и доступен для всех, кто участвует в жизненном цикле API. Его синтаксис лаконичен, но выразителен. С помощью API Blueprint вы можете быстро проектировать и создавать прототипы API-интерфейсов, а также задокументировать и тестировать уже развернутые критически важные API-интерфейсы.
Вкратце API Blueprint - это язык, который позволяет гибко описывать API, охватывающий множество вариантов использования (примеры здесь).
Пасека позволяет импортировать API Blueprint, проверять его на лету и предоставлять вызываемый URL-адрес API, чтобы сразу же попробовать его и не ждать реальной имплантации. Я знаю, это звучит как магия, но давайте перепишем нашу спецификацию API с помощью API Blueprint и посмотрим, что произойдет.
Схема API
Вы можете найти больше информации о синтаксисе в документации, но вот несколько простых принципов описания API:
# Группа ресурсов (в данном случае сообщения)
## Путь к ресурсу (в данном случае / posts)
### Действие по спасению (в данном случае GET и POST)
Раздел Структура данных немного отличается. Его основная функция - предоставлять повторно используемые блоки данных, которые можно использовать в запросах или ответах (избегайте дублирования).
Поскольку у Apiary есть предварительный просмотр в реальном времени, вы можете легко скопировать / вставить (или синхронизировать с репозиторием Github) свой API Blueprint и посмотреть, как он выглядит и действительно ли он.
Как видите, план действителен, и документация создана. После внесения изменений Apiary проверит документ, и в случае возникновения каких-либо проблем вы увидите:
Как мне сразу воспользоваться? Просто перейдите к действию ресурса, и вы получите все подробности, чтобы его вызвать:
Apiary предоставляет URL-адрес фиктивного сервера, который вы можете использовать для отправки запросов. И как только вы внедрили настоящий API, вы можете обновить хост в чертеже и попытаться выполнить те же запросы.
Кроме того, вы можете заметить, что запрос POST / posts включает в себя два ответа, один для успеха (код состояния 201) и один для отказа (код состояния 400), по умолчанию, когда вы делаете запрос по предоставленному URL-адресу. получит первый ответ, который в данном случае равен 201, но если вы хотите увидеть результат в случае 400, вам необходимо указать заголовок Prefer, где значение - желаемый код статуса, подробнее по ссылке.
Полученные результаты
С API Blueprint не осталось вопросов о структуре запросов / ответов, а благодаря Apiary работа может быть начата сразу после того, как API Blueprint будет готов.
Обобщить
Если вы думаете, что накладных расходов и простого текстового описания достаточно для совместной работы с другими членами команды, я искренне рад за вас, поскольку вы работаете в хорошо сбалансированной команде. Но даже в этом случае актуальную документацию никто не отменял.
Я надеюсь, что один из этих инструментов (API Blueprint или Swagger) поможет вам решить проблемы со сборкой API, поскольку он помог мне или, если вы уже используете его, поделитесь, какие подводные камни вы обнаружили, в разделе комментариев ниже.
