Как не стрельнуть себе в ногу при описании 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.
Фронт — не экстрасенс, ему важны детали.
✔ Если вам кажется, что надо что-то изменить, то вам не кажется и надо менять.
✔ Валидируйте свои спеки через других, так как может замылиться глаз.
➖➖➖
А что вы думаете на этот счет и как оформляете?