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

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

Комментарии (2)


  1. Kwisatz
    02.11.2022 21:10
    +1

    Лишние бессмысленные слова в названиях ресурсов и полей. Названия company_info, address_details, country_code будут выглядеть лучше, если вместо них использовать company, address, country

    Нет не будут

    entity.country.code или entity.countryCode

    В обоих случаях хотя бы примерно понятно о чем речь.

    Лишних и бессмысленных слов в названии быть не может, иначе рано или поздно вы окажетесь в ситуации где у вас сущность на 200 полей, а вам нужно по каждому нырять в документацию, которая устарела. И в поле currency разом окажется $, RUB, руб и прочее.

    PS у меня при прочтении статьи в голове не пропадало ощущение что пол дизайнера пропадет если перейти на JsonRPC а вторая если перейти вообще на GraphQL


    1. 57uff3r Автор
      03.11.2022 10:07

      Сущность в 200 полей с разнородными значениями + плохая документация — это как раз пример того, что случается, когда дизайн не определяется централизованно. Гайдлайны и линтеры как раз для того, чтобы поля назывались одинаково в разных сервисах и в них лежали всегда одинаковые значения.

      Год от года рынок специалистов по дизайну и выпуску API растет и требует больше народу. Наладить выпуск и контроль качества в продукте, который, например, построен из 1000 микросервисов и все они должны одновременно показывать клиенту однородный и консистентый дизайн — это непростая задача. Причем с технологиями типа GraphQL тоже хватает мест, где накосячить (даже с теми же названиями и списками полей)

      Как индикатор роста спроса на такого рода услуги выступают конференции вроде https://www.apidays.global/ — это уже 20-30 эвентов каждый год, на которых вырабатываются новые стандарты, решаются проблемы поддержки, запуска и тестирования публичных и приватных API интерфейсов. А хороший инженер по контролю за API сейчас стоит больше $100 000 в год