Рекомендации по интеграции с остальным API цифрового профиля и внедрению веб-сервисов RESTful

Получение данных об организациях возможно только при использовании offline-режима получения данных о пользователе. Этот процесс включает следующие шаги:

1. Проведение аутентификации пользователя с помощью offline-режима, по результатам которого у вызывающей системы будет следующая информация:

• идентификатор (oid) организации, по которой необходимо получить детальную информацию. Для получения oid можно воспользоваться блоком о ролях пользователя (roles), который доступен при наличии разрешения «Просмотр списка организаций пользователя» (usr_org);
• актуальное значение ключа доступа «scsToken».

2. Вызов специального сервиса ESIA-Bridge, позволяющего получить данные об организации. Для этого необходимо выполнить HTTP-запрос методом POST на адрес точки получения данных об организации (/blitz/bridge/organization). Особенности запроса:

• в теле (body) запроса необходимо указать параметры “token” (значение актуального ключа доступа), “oid” (идентификатор организации) и “redirect_url” (адрес обработчика успешной аутентификации на стороне вызывающей системы);
• в заголовке (http header) необходимо указать параметр “Content-Type” со значением “application/x-www-form-urlencoded”.

Пример запроса на получение данных об организации:

Возможные варианты ответа ESIA-Bridge на такой запрос:

Все, что требуется системе, – направить браузер пользователя по ссылке из ответа, указав корректный hostname ESIA-Bridge. Переход по этой ссылке инициирует в ЕСИА получение разрешения на доступ к данной организации. После того, как пользователь даст разрешение, ESIA-Bridge вернет пользователя по адресу, указанному в redirect_url и поставит новую сессионную cookie с новым ключом доступа tokenSCS. Получив обновленный ключ доступа, система должна повторно вызвать сервис получения данных об организации.

• если ключ доступа позволяет получить данные указанной организации, то в ответе будет получен json со следующими данными:
• обновленный ключ доступа scsToken, при этом старый ключ перестает действовать;
• сведения об организации согласно спецификациям ЕСИА.

Пример ответа, содержащего в себе данные организации, ее сотрудников и филиалов:

После получения ответа рекомендуется сохранить данные обновленного ключа доступа scsToken. Это позволит в будущем обновить данные об организации, ее сотрудниках и филиалах в offline-режиме, т.е. без участия пользователя.

Общие положения

Взаимодействие клиентской системы с сервисами шлюза, обеспечивающими идентификацию пользователей через ЕСИА, происходит через стандартный протокол OAuth 2.0/OpenID Connect. Авторизация в ЕСИА происходит, в данном случае, как обычная OAuth авторизация.

Для работы с данным протоколом имеются готовые открытые реализации под большинство популярных программных платформ.

Чтобы начать работу с ЕСИА Шлюзом необходимо интегрировать в целевую информационную систему одно из готовых средств, реализующих работу с протоколом OAuth 2.0.

Спецификация OpenID Connect

Взаимодействие по защищённому протоколу

В соответствии с ч. 19 и ч. 21 ст. 14.1 Федерального закона от 27.07.2006 №149-ФЗ “Об информации, информационных технологиях и о защите информации” для обеспечения защиты передаваемых биометрических персональных данных от актуальных угроз безопасности должны применяться сертифицированные средства криптографии (шифрования). Таким образом каждый пользователь, инициирующий (по средством браузера) соединение, с целью проведения процедур биометрической идентификации должен быть уведомлён о необходимости установки российских сертифицированных средств криптографической защиты если таковые не были установлены в его браузере. В случае отказа пользователя от использования российских сертифицированных средств криптографической защиты его необходимо уведомить о рисках перехвата биометрических персональных данных злоумышленником, для дальнейшего их использования в мошеннических целях.

Браузеры, поддерживающие российские сертифицированные средства криптографической защиты:

• Яндекс.Браузер версии 19.3. и выше
• Спутник версии 4.1 и выше
• Internet Explorer версии 11.0.9600 и выше

• КриптоПРО CSP 5.0
• ViPNet CSP Win 4.4 Windows RUS

Контроль использования российских сертифицированных средств криптографической защиты возлагается на клиентскую систему (КИС), являющуюся стороной, по средством которой пользователь инициирует процесс биометрической идентификации.

Доступ к сервисам шлюза

Для доступа к сервисам шлюза необходимо с помощью функциональных инструментов его административной панели создать КИС, указав в её параметрах «Пути возврата» – URL-адрес(а) клиентской ИС (потребителя идентификации), на которые шлюз будет отвечать после выполнения авторизации.

Для доступа к сервисам шлюза потребуются следующие реквизиты:

• адрес шлюза (например, адрес демо стенда RNDSOFT https://gate.esia.pro/);
• идентификатор клиента (например, a4fb804bfdf54df4f4da7faae24375e6);
• секрет клиента (например, 6cd6a2bd732bb66fed6ff7fd7ca2442ccc316a8e6764cbea4e8ad589407a4c28);
• страница с конфигурацией OАuth https://gate.esia.pro/.well-known/openid-configuration

Значение идентификатора и секрета для КИС берутся из её параметров в административной панели шлюза.

ЕСИА Шлюз не занимается валидацией скоупов, переданных клиентской системой. Скоупы просто передаются в ЕСИА. Поэтому .well-known/openid-configuration содержит пустой массив в scopes_supported.

Схемы процесса взаимодействия между Клиентской ИС, ЕСИА Шлюзом и ЕСИА/ЕБС/ЦПГ

ЕСИА Шлюз не хранит персональные данные пользователей в базе данных. Передача персональных данных пользователя происходит через защищенный по https канал связи.

ЕСИА Шлюз хранит только транспортную информацию (scopes, redirect_uri, время запроса, авторизационный код ЕСИА) и SHA-512 от ФИО и СНИЛСа пользователя. Эти данные необходимы для обработки внештатных ситуаций, таких как составление заявки в службу поддержку ЕСИА и реагирование на запросы правоохранительных органов и не являются персональными данными.

Общее описание HTTP API предоставляемого со стороны ЕСИА Шлюз

В данном разделе приводится пошаговое взаимодействие клиентской системы и шлюза, доступного по адресу https://gate.esia.pro/ В качестве клиентской ИС рассматривается система с идентификатором a4fb804bfdf54df4f4da7faae24375e6, секретом 6cd6a2bd732bb66fed6ff7fd7ca2442ccc316a8e6764cbea4e8ad589407a4c28 и путем возврата https://ya.ru

Авторизация (Получение авторизационного кода)

Для инициации процесса идентификации и аутентификации пользователей через ЕСИА необходимо сформировать авторизационный запрос и передать его на соответствующий URL шлюза. Для пользователя с вышеуказанными параметрами ссылка будет иметь следующий вид.

Получения данных об организации

Указать в параметре scope необходимые значения, соответствующие методическим рекомендациям (допустимые значения scope приведены в таблице ниже).
Согласно регламенту ЕСИА scope org_# нужно формировать запросом вида scope=“http://esia.gosuslugi.ru/org_emps?org_oid=1000000357”
В таблице 24 регламента есть информация про org_# и формирование запроса.

Сначала необходимо сформировать первичный запрос для получения идентификатора организации ЕСИА.
Первый запрос на получение списка компаний и идентификатора:

После получения идентификатора, необходимо отправить запрос на получение данных организации.
На пример запрос на получение Инн по компании:

Для идентификации пользователя через ЕБС требуется:

• Изменить значение параметра provider на ebs_oauth;
• В параметре scope указать openid bio.

Для получения данных Цифрового профиля требуется:

• Изменить значение параметра provider на cpg_oauth;
• В параметре scope указать openid;
• указать опциональный параметр responsible_object – Иванов Иван Иванович.

Должна получиться ссылка вида:

https://demo.gate.esia.pro/auth/authorize?client_id=a4fb804bfdf54df4f4da7faae24375e6response_type=codescope=openidredirect_uri=https://ya.ruprovider=cpg_oauthpermissions=fullnamepurposes=CREDITsysname=CREDITactions=ALL_ACTIONS_TO_DATAexpire=3responsible_object=Иванов Иван Ивановичstate=1a73f168-4485-11ed-b878-0242ac120002

Для запроса нескольких целей согласия нужно указать их в запросе в параметре purposes=
Должна получиться ссылка следующего вида:

В случае успешной авторизации произойдет редирект на url следующего вида

где, в параметре code передается авторизационный код.

В случае возникновения ошибки будет редирект на url возврата с указанием ошибки

где, в параметрах error и error_description хранится информация об ошибке.

Получение токена доступа (Обмен авторизационного кода на токен доступа)

• grant_type – тип разрешения (допустимое значение authorization_code);
• redirect_uri – путь возврата специфичный для конкретного клиента;
• client_id – идентификатор клиента;
• code – авторизационный код;
• client_secret – секрет клиента.

На предыдущем шаге после успешной авторизации в ЕСИА был получен авторизационный код, который следует обменять на токен доступа (access_token) для его последующего использования при получении пользовательских данных. Один код можно обменять только на один токен. Для этого отправляем POST запрос на url

со следующими параметрами запроса:

• grant_type=authorization_code;
• redirect_uri=https://ya.ru – путь возврата специфичный для конкретного клиента;
• client_id=a4fb804bfdf54df4f4da7faae24375e6 – идентификатор клиента;
• code – авторизационный код;
• client_secret=6cd6a2bd732bb66fed6ff7fd7ca2442ccc316a8e6764cbea4e8ad589407a4c28 – секрет клиента.

Пример запроса получения access_token:

curl POST https://demo.gate.esia.pro/auth/token

Будет получен следующий ответ:

В поле access_token находится токен доступа необходимый для получения данных. А в refresh_token находится токен обновления необходимый для перевыпуска токена доступа. refresh_token присутствует в ответе только для провайдеров данных esia_oauth и cpg_oauth.

Перевыпуск токена доступа (Обмен токена обновления на токен доступа)

• grant_type – тип разрешения (допустимое значение refresh_token);
• redirect_uri – путь возврата специфичный для конкретного клиента;
• client_id – идентификатор клиента;
• refresh_token – токен обновления;
• client_secret – секрет клиента.

Доступно только для провайдеров данных esia_oauth и cpg_oauth!

На предыдущем шаге были получены токены доступа и обновления. Токен обновления можно обменять на новые токены доступа (access_token) и обновления (refresh_token) для последующего использования при получении пользовательских данных. После перевыпуска токенов предыдущие токены доступа и обновления перестают работать. Для этого отправляем POST запрос на url

• grant_type=refresh_token;
• redirect_uri=https://ya.ru – путь возврата специфичный для конкретного клиента;
• client_id=a4fb804bfdf54df4f4da7faae24375e6 – идентификатор клиента;
• refresh_token=GeIXIpZ1R1IXL5uGI7AZKJUS8Q-mQEOJFrHRhJcn2cM – токен обновления;
• client_secret=6cd6a2bd732bb66fed6ff7fd7ca2442ccc316a8e6764cbea4e8ad589407a4c28 – секрет клиента.

Пример запроса на перевыпуск токенов:

Получение данных пользователя

Для получения данных отправляется GET или POST запрос на url

со следующими заголовками запроса:

Пример запроса на получение данных:

На основе полученного токена доступа шлюз предоставляет клиентским системам доступ к областям данных из защищённого хранилища ЕСИА.

ВАЖНО! В соответствии с законодательством перечень скоупов доступных для клиентских систем шлюза может быть ограничен. Поэтому, прежде чем указывать перечень скоупов в запросе к шлюзу, необходимо сверить этот перечень с перечнем скоупов указанных в заявке на подключение к тестовой/промышленной ЕСИА.

Полный перечень скоупов и соответствующих им данных, которые могут быть запрошены из защищённого хранилища ЕСИА можно найти в методических рекомендациях по использованию ЕСИА.

Получение документов из Цифрового профиля

Запрос документов происходит так же, как и запрос других данных – путем указания нужного scope. Но в случае запроса документа ответ может поступить не сразу, а в течении некоторого времени.
В случае, если сведение запрошено в ведомстве и ответ еще не поступил, возвращается
идентификатор этого запроса и идентификатор пользователя (oid). С помощью идентификатора
запроса осуществляется процесс обработки персональных данных. Для возможности получения
сведения о документах необходимо обновить запрос. Для типа документа
INCOME_REFERENCE (Справка о доходах и суммах налога физического лица (форма 2-НДФЛ))
дополнительно указывается параметр year – год, за который успешно получена справка 2-НДФЛ
в ведомстве.
В случае, если у пользователя нет информации по следющим сведениям: FID_BRTH_CERT,
OLD_BRTH_CERT, RF_BRTH_CERT, MARRIED_CERT, DIVORCE_CERT,
NAME_CHANGE_CERT и FATHERHOOD_CERT, то в ответе на запрос вернется ошибка 404.
Перечень параметров, которые возвращаются по каждому типу документа (doc_type),
приведены в разделе 7.2 методических рекомендаций.

Выписка с данными в исходном виде

Получение данных о документах в исходном виде происходит так же путем указания scope.
Сервис доступен для типов документов VEHICLE_INFO (Выписка
о транспортном средстве по владельцу), ILS_PFR (Сведения о состоянии индивидуального
страхового счета застрахованного лица), PAYOUT_INCOME (Сведения о доходах
физического лица и о выплатах страховых взносов, произведенных в пользу физического
лица). Но в случае запроса данных ответ может поступить не сразу, а в течении некоторого времени.
В случае, если сведение запрошено в ведомстве и ответ еще не поступил, возвращается
идентификатор этого запроса и идентификатор пользователя (oid). С помощью идентификатора
запроса осуществляется процесс обработки персональных данных. Для возможности получения
сведения о выписки транспортого средства по владельцу необходимо обновить запрос. Перечень
параметров, которые возвращаются по каждому типу документа (doc_type), приведен в разделе
7.2 методических рекомендаций.

Пример ответа в случае запроса openid и fullname из защищённого хранилища ЕСИА:

Получение согласий пользователя из Цифрового профиля

На основе полученного токена доступа шлюз предоставляет список всех согласий пользователя, выданных клиентской системе.

Выход из системы ЕСИА

• client_id=a4fb804bfdf54df4f4da7faae24375e6 – идентификатор клиента;
• redirect_uri=https://ya.ru/callback – путь возврата специфичный для конкретного клиента, на который будет перенаправлен пользователь;
• state – набор случайных символов, имеющий вид 128 битного идентификатора запроса, сформированного по стандарту UUID. Должен отличаться от набора, использованного для получения авторизационного кода. Необходим для предотвращения CSRF атак.

Для получения данных отправляется GET запрос

Для инициации процесса выхода из системы ЕСИА необходимо сформировать авторизационный запрос и передать его на соответствующий URL шлюза. Для пользователя с вышеуказанными параметрами ссылка будет иметь следующий вид:

ВАЖНО! Путь возврата пользователя обязательно должен быть указан в соответствующей КИС

Также, необходимо добавить на тех.портал ЕСИА url вида https://gate.esia.pro/auth/esia_oauth/logout_callback

После завершения сессии в системе ЕСИА пользователь будет перенаправлен на адрес, указанный в параметре redirect_uri

Время на прочтение

Раскрываем 12 кейсов проектирования спецификации REST API из практики red_mad_robot, которые помогут сэкономить время для разработки. А также объясняем, почему стоит следовать подходу contract first — писать спецификацию прежде кода.

Статей, объясняющих основы архитектурного стиля REST, больше, чем символов в этом тексте. Самих принципов всего шесть, но они дают большой простор для реализации задач разными способами. В этой статье ведущий backend‑разработчик red_mad_robot Серёжа Ретивых делится дополнительными правилами, которые мы выработали и применяем у себя в red_mad_robot на практике. Начнём с общих терминов, а если вам всё это знакомо, перепрыгивайте сразу в блок «Рекомендации проектирования для REST API».

Что такое REST API и зачем он нужен

Современные информационные системы и весь интернет базируются на работеклиент‑серверной архитектуры. Принцип этой работы заложен в названии: сервер хранит, обрабатывает данные и предоставляет их по требованию, а клиенты запрашивают данные и предоставляют их в удобном для пользователя виде. Например, любое приложение в смартфоне, которое работает с доступом в интернет, — это клиент. В сложных системах (то есть любых системах с интеграцией, которые не хранят абсолютно все используемые данные в себе), сервер может сам обращаться к другим серверам за нужными данными: в таких случаях он выступает для них клиентом.

Сервер предоставляет клиенту API (англ. Application programming interface) — это способ взаимодействия с собой, а для его описания служат контракты. Они однозначно интерпретируют передаваемые данные, а также дают возможность понять, что сервер вообще умеет делать.

Контракт может быть описан как угодно, но лучше использовать общепринятые подходы, чтобы работать с ним было удобно всем. Например, существует SOAP — целый протокол, которому нужно формально следовать. Он распространён повсеместно, но морально уже давно устарел.

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

Если ваш сервис реализован в соответствии с этим подходом, его можно называть RESTful, и он будет предоставлять REST API. Но также REST API можно назвать документ спецификации, в котором описан такой контракт.

Спецификации тоже можно писать и форматировать по‑разному. Поэтому по мере развития выработался стандарт OpenAPI — самый распространённый и понятный формат. Мы в red_mad_robot используем его.

Почему стоит писать спецификацию прежде кода

Так, разобрались с тем, что такое контракт и спецификация. А когда она появляется и в каком виде? Обычно задача в голове разработчика имеет приблизительные очертания и проясняется по мере написания кода. Когда задача готова, можно уже однозначно сказать, каким образом использовать функциональность и сгенерировать документацию. Это интуитивно понятный и простой подход — и поэтому широко распространённый. Он экономит нам время на написании документации, но на этом его преимущества заканчиваются.

Мы в red_mad_robot стараемся писать спецификацию прежде кода, и вот почему.

Скорость разработки

Для потребителей API реализация становится неблокирующим фактором, и мы быстрее параллелим процесс разработки, поскольку можем договориться о контракте — и каждый спокойно займётся своим делом. Да, мы тратим дополнительное время на этапе проектирования, но не ждём сюрпризов по итогу реализации.

Моковый сервер

Из спецификации можно автоматически генерировать актуальный моковый сервер и делать жизнь потребителей API ещё лучше.

Моковый сервер (англ. mock — заглушка) — временный прототип будущего сервера, который точно реализует контракт или его часть. Он не содержит никакой логики внутри, а каждый раз отвечает одними и теми же заранее подготовленными данными. В нашем случае эти подготовленные данные и есть данные примеров в спецификации.

Кастомизация API

Проектирование API руками не ограничено скудной функциональностью генератора и позволяет сделать его по-настоящему удобным для конкретной задачи.

Гибкость процесса

Писать спецификацию могут как разработчики, так и аналитики, появляется дополнительная гибкость в процессе — можно эффективно делить задачи и планировать время.

Дополнительный контроль схемы данных

Вы формально описываете все потоки данных и при наличии вложенных полей быстрее выявите непроработанные сценарии. Также повышается вероятность уловить ситуацию лишних вложенных данных, поскольку, скорее всего, вы описываете только те данные, которые будут непосредственно нужны.

Представим, что есть книга с идентификатором и автором. Если автор — просто строка, вложенных данных нет. А если автор, в свою очередь, имеет идентификатор, ФИО и возраст, и мы их также передаем внутри книги, то автор — вложенные данные.

Пример первый. Есть простой GET-запрос профиля пользователя, оценённый как мэппинг данных из одной таблицы базы данных в JSON-объект. Мы публикуем спецификацию, Frontend приходит с запросом — в дизайне ещё есть поле «Бонусы». И вот нам уже нужно делать интеграцию или асинхронно подготавливать данные.

Пример второй. Разработчики не любят писать лишний код. Если ранее был реализован сериализатор для модели А с вложенным объектом В, то дальше он везде и будет использоваться. Необходимости в В для конкретного эндпоинта может и не быть, но будет лишний JOIN в хорошем случае и SELECT в плохом.

Сериализатор превращает данные из удобного для нас внутри кода формата в тот вид, в котором мы вернём его согласно спецификации. Обычно схема, в которую сериализатор преобразует данные, может содержать вложенности.

Рекомендации проектирования для REST API

Итак, сначала спецификация — потом реализация. Вот правила, которым мы следуем помимо общепринятых.

Если из эндпоинта нужно вернуть данные, всегда оборачивайте их в объект

Эндпоинт (англ. endpoint — конечная точка) — метод вашего сервиса, предоставляемый для использования. Выполняет конкретную задачу, принимает параметры и данные, возвращает данные.

• эндпоинт проще расширять (например, добавить поля для постраничной навигации);
• «фронту» иногда проще парсить ответ, особенно если возвращается массив;
• субъективно проще воспринимается.

JSON (JavaScript Object Notation) — формат данных, который выглядит как объект в JavaScript, отсюда и название.

При встраивании данных отдавать предпочтение объектам, а не плоской (одномерной) структуре полей с префиксами

Ошибки бизнес-логики плохо сопоставляются с http-кодами. Особенно код 400: в эту ошибку обычно помещается масса кейсов — и неправильно введённый пользователем код OTP, и ошибки валидации формы, и ошибки операций, недоступных пользователю по бизнес-процессу. Без явного описания только по коду о них невозможно узнать.

Мы договорились использовать следующий формат ошибок:

Возможно добавление поля с ошибками валидации дополнительно. Ошибки 401, 403, 404, 500 стоит вынести якорем и вставлять в YAML 1–4 строками.

Не выносите в схемы (/components/schemas) эквивалент модели в базе данных. Скорее всего, на каждый запрос будет своя схема

Одна сущность в базе данных будет иметь разные представления в разных запросах. Например, в списке пользователей достаточно краткой информации, при создании пользователя нужно дополнительно передавать пароль, а в профиле — ещё поля из других таблиц, например баланс на счёте.

При кодогенерации и статической типизации вопрос схемы для ответа в коде однозначно определён и не вызывает раздумий, а расширение любого компонента происходит независимо.

На любой запрос мы возвращаем ответ, который имеет схему. Можно на каждый ответ при реализации писать свою схему. Но когда у нас есть спека, из которой мы сгенерировали код, схема готова и на этапе написания кода не нужно ничего придумывать. Благодаря этому можно отдать задачу на реализацию кому-то ещё и быть уверенным, что всё будет в порядке.

Есть альтернативный вариант с ModelShort и ModelDetails схемами. Но велик риск, что рано или поздно потребуется схема ModelDetailsWithExtra и ей подобные, а пересечение моделей в разных запросах начнёт замедлять разработку (или выполнение запроса за счёт подготовки лишних данных).

Минимизируйте вложенность в URL

В случае иерархии данных длинный URL менее удобен в использовании. Обычно нам достаточно иметь только идентификатор родительской сущности в пути запроса. Это никак не влияет на фильтрацию, идентификатор прародителя легко достать из родителя.

Для сериализации массива в параметрах запроса используйте style

Эти параметры OpenAPI описывают понятный формат «?colors=red,green,blue». В случае кодогенерации убедитесь, что эта часть стандарта поддерживается и код адекватно работает.

Для идентификаторов используйте UUID

UUID — это стандарт идентификации, используемый в создании программного обеспечения Основное назначение UUID — это позволить распределённым системам уникально идентифицировать информацию без центра координации.

• дополнительная защита от несанкционированного доступа к объектам путём инкрементального перебора идентификаторов (если не сделана проверка на владение ресурсом);
• дополнительная помощь при ситуации объединения данных в одну таблицу из двух источников — практически нет вероятности дублирования ключа; в спецификации для строк предусмотрен специальный format: uuid.

Не передавайте в строке запроса персональные данные и секреты, например токены доступа

Очевидный факт, но проговорим на всякий случай.

Исключение: допустимо в случае одноразового токена.

Мотивация: эти данные попадут в логи и могут быть получены третьими лицами. Это небезопасно.

Определитесь со стандартом и форматом дат

Например, используйте iso-8601 YYYY-MM-DDThh:mm:ss±hh. Подумайте про таймзоны и лучше по умолчанию сразу их используйте.

Мотивация: ситуации, когда локального времени становится недостаточно, происходят чаще, чем кажется. Внедрение таймзоны в процессе влечёт проблемы с миграцией данных. Использование с самого старта не требует накладных расходов — сложность разработки не растёт и этот формат ничему не мешает.

Версионируйте API

И сразу используйте префикс /api/v1.

Мотивация: использование префикса тоже не требует лишних расходов, зато проще отделить новую независимую мажорную версию. Для семантического версионирования и создания чейнджлогов в автоматическом режиме хорошо использовать Bump.sh (можно ограничиться бесплатным тарифом).

Семантическое версионирование (SemVer) — это правила именования версий библиотек для обозначения ключевых изменений. Эти сведения помогают разработчикам понять, совместима ли конкретная версия с проектами, в которых использовались предыдущие версии.

Если чейнджлоги собираются автоматически, можно просто прикрепить на них ссылку в спецификации. Версии вносят формальную асинхронную коммуникацию в работу команды. Просто так Frontend не будет каждый день обновлять спецификацию и искать, когда появится нужный ему метод.

Минимизируйте ответ в JSON

Мотивация: если убрать все отступы и пробелы, по сети придётся передавать меньше данных, но читать такой массив текста сложнее. Чтобы упростить чтение, можно определять формат в соответствии с заголовком Prefer return=minimal или return=representation.

Заполняйте примеры полей example в спецификации

Мотивация: в некоторых ситуациях при использовании мокового сервера дефолтные нули могут мешать Frontend дальше совершать какие-то действия. И они вынуждены ждать реализацию (например, 0 на счёте не даёт возможности перейти дальше по флоу). А пример с осмысленными данными (а не только 0 и string) воспринимается понятнее, и в некоторых случаях формат строки для Frontend тоже может иметь значение.

Вывод

В сети много стайлгайдов по написанию чистого и лаконичного кода и намного меньше гайдов для API. Но контракты используются на более высоком уровне, чем код. Поэтому интеграция с плохо спроектированным сервисом влияет и на другие части системы, в то время как грязный код хотя бы остаётся локализован внутри.

Мы формируем свой стайлгайд, который будет делать спецификации более строгими и однозначными, и мы поделились основными такими моментами. Если у вас есть хорошие правила из вашей практики, обязательно пишите их в комментариях — сделаем контракты чистыми и прозрачными.

Кстати, у нас открыта вакансия Java-разработчика.

Над материалом работали:

• текст — Серёжа Ретивых, Ника Черникова,
• редактура — Виталик Балашов,
• иллюстрации — Марина Черникова.

Делимся железной экспертизой от практик в нашем телеграм-канале red_mad_dev. А полезные видео складываем на одноимённом YouTube-канале. Присоединяйся!