Как не стрельнуть себе в ногу при описании API?

Вчера смотрел доку на REST метод и увидел: в выходных параметрах поле PRICE, а в примере - значение 0.

Что же здесь не так? Так то, что цена без копеек — это что-то из параллельной вселенной.

На мой вопрос коллеге: «Почему так?», получил ответ: «Какая разница? JSON принимает number».

С одной стороны, формально прав, ведь number действительно принимает и целые числа, и числа с плавающей точкой, но на практике — путь по скользкой дорожке, потому что она ведет к недопониманию:

- Разработка увидит пример и сделает Ctrl+C + Ctrl+V,

- Интеграторы подумают: "Аналитик указал integer, значит так и надо".

Почему я уверен, что будет так?

Потому что, когда-то в Альфе мы интегрировали UI-витрину с бэк-сервисами: фронт бежал вперёд, контракты были «на бумаге», в доке от бэка для поля с “неочевидными значениями” было написано число, а в примере - гордо красовался 0.

Как честный человек, я так и заложил, а бизнес подтвердил, что будет целое число.

И что по итогу?

▪️ Бэк внезапно заложил float,

▪️ На проде прилетает 12.34,

▪️ Фронт, конечно же, округляет до 12 и вызывает недоумение у заказчика,

▪️ Версию мобилки обновить быстро нельзя.

Виноват ли фронт? Нет.

Виноват ли бэк? Тоже нет.

Просто спеки не дожали, детали не учли.

➖➖➖

Как избежать такие кейсы?

1️⃣ Примеры должны быть реалистичными

- Если ожидаете float → показывайте 0.0, 12.99

- Если ожидаете integer → пусть будет 0, 42

2️⃣ Формат числового значения — must have!

Не просто пишите number.

Уточните формат, хотя бы number(19,2)

3️⃣ Минимизируйте двусмысленности

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

✖️ Неправильный пример → неправильное восприятие → баги

4️⃣ Согласуйте правила в команде

Документируйте

Если параметр — число, всегда указываем его тип и пример.

Например, везде где я работал, я всегда пишу int или float, а разрабы и так понимают, что в JSON будет number, но при этом им на берегу все очевидно из спеки.

➖➖➖

На что ещё стоит обратить внимание?

✔️0 — это не всегда float.

Если ожидаете дробное, используйте 0.0.

✔️Ваши примеры — это ориентир для всех, кто будет работать с API.

Фронт — не экстрасенс, ему важны детали.

✔️ Если вам кажется, что надо что-то изменить, то вам не кажется и надо менять.

✔️ Валидируйте свои спеки через других, так как может замылиться глаз.

➖➖➖

А что вы думаете на этот счет и как оформляете?

1 минута

5 января 2025