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

А что делать тем, кто разрабатывает приложения без интерфейсов? Например, 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]*)*$

Наш набор правил для линтинга тоже доступен в репозитории.

Берите и пользуйтесь, хороших и чистых апишек вам!

Примечание от Geekfactor.io: Эта статья написана СТО компании - клиента Geekfactor Monite Андреем Корчаком (ака @57uff3r). Мы решили поделиться тем, какие классные штуки делают программисты, которых мы помогаем находить. Вы также можете подписаться на блог Андрея про управление командами разработки "Психиатрия и системный дизайн".

Обложка: icons8