Когда разрабатываешь традиционное приложение (веб или мобильное) — то совершенно понятно, как сделать в нем хороший интерфейс. Зовем мудрых дизайнеров, создаем гибкую и красивую дизайн-систему со всеми нужными элементами, потом на ее основе создаем экраны, которые последовательно, просто и логично отражают все пользовательские сценарии.
А что делать тем, кто разрабатывает приложения без интерфейсов? Например, API-first компании, поставляющие машиночитаемые интерфейсы для других компаний и приложений? У API приложений нет кнопок и форм, но интерфейсы, тем не менее, у них есть — API ресурсы, методы, параметры и их взаимная организация.
Во многих компаниях над структурой API не заморачиваются — отдают их определение целиком в руки разработчиков, которые худо-бедно знакомы с организацией REST ресурсов или RPC вызовов. И разработчики в целом с этой задачей справляются. Но любой (API или графический) интерфейс, сделанный и спроектированный разработчиками, будет явно не так изящен и аккуратен, как решение профессионального дизайнера.
Какие шероховатости чаще всего встречаются в API интерфейсах, которым не уделили должного внимания?
Путаница с кодами ответов. Например, 401 и 403 — вроде похожие по сути статусы, но совершенно разные по смыслу.
Лишние бессмысленные слова в названиях ресурсов и полей. Названия
company_info,address_details,country_codeбудут выглядеть лучше, если вместо них использоватьcompany,address,country.Микс различных вариантов разделения слов в строках — дефисы, подчеркивания, кэмелкейс. Например,
https://api.example.com/v1/sales-orders,https://api.example.com/v1/sales-orders>/addressInfoНекорректное использование глаголов в тех местах, где должны быть существительные —
https://api.example.com/v1/navigateвместоhttps://api.example.com/v1/directions.
Конечно, это не полный список проблемных мест и тонкостей, которые возникают при проектировании API. Более того, когда много разработчиков работают вместе, каждый из них делает свои собственные ошибки, которые только усугубляют творящийся хаос.
Чтобы API интерфейсы были красивые и консистентные, за их дизайном нужно целенаправленно следить. И занимается этим специальный человек — API дизайнер. Все публичные API интерфейсы, которые релизятся компанией, должны соответствовать определенному стандарту. API-дизайнеры создают и поддерживают эти стандарты, а также контролируют, чтобы результаты труда программистов этим стандартам соответствовали.
Основной артефакт работы такого дизайнера — API дизайн гайдлайны, которые в мелочах описывают, как API сервисы должны выглядеть и работать.
Разработка таких гайдов — процесс не самый быстрый и простой, поэтому у большинства проектов, которые хотят иметь крутые публичные апишки, есть только один вариант — брать готовые стандарты и работать по ним.
Я работаю в API компании Monite, и API интерфейсы — наше лицо. Поэтому мы потратили время и силы на разработку API дизайн гайдлайна под наши нужды и опубликовали его на github. Этот гайдлайн затрагивает практически все вопросы, которые так или иначе возникают перед программистами:
Конвенции для именования объектов;
Заголовки;
Параметры, запросы и их комбинации;
Ответы сервисов;
Форматы данных запросов и ответов.
Правил много, и проверять все API интерфейсы на соответствие правилам сложно и долго. Поэтому для автоматизации рутинных проверок мы используем OpenAPI линтер. Это небольшая программа, которая получает на вход OpenAPI файл и прогоняет его через правила, описанные в отдельном репозитории.
Мы используем самый популярный API Linter на сегодня — Spectral.
npm install -g @stoplight/spectral-cli
Пользоваться линтером просто — нужно скормить ему yaml с OpenAPI описанием вашего проекта и yaml файл с правилами. На выходе вы получите список того, что надо пофиксить.
Правила писать к линтеру тоже просто — там есть свой очень простой декларативный язык с проверками, операторами и регулярками.
# ################################################################################################
# Section 10: HTTP headers #
# This ruleset covers the HTTP headers rules from the Monite API Style guide #
# <https://github.com/team-monite/api-style-guide/blob/main/Guidelines.md#section-10-http-headers> #
# ################################################################################################
rules:
monite-headers-kebab-case:
message: Header parameters must be kebab-case
severity: error
given: "$.paths.*.*.parameters[?(@.in=='header')].name"
then:
function: pattern
functionOptions:
match: ^([a-z]*)(-[a-z0-9][a-z0-9]*)*$Наш набор правил для линтинга тоже доступен в репозитории — https://github.com/team-monite/api-style-guide/tree/main/spectral.
Берите и пользуйтесь, хороших и чистых апишек вам!
Примечание от Geekfactor.io: Эта статья написана СТО компании - клиента Geekfactor Monite Андреем Корчаком (ака @57uff3r). Мы решили поделиться тем, какие классные штуки делают программисты, которых мы помогаем находить. Вы также можете подписаться на блог Андрея про управление командами разработки "Психиатрия и системный дизайн".
Обложка: icons8
