Что описывать в REST сервисе кроме данных
Что проверяют
Умеете ли вы описывать контракт, а не таблицу полей. Аналитику ставят задачу так, что по его документу разработчик пишет сервис, а тестировщик проверки, поэтому спрашивают, что обязано быть в описании кроме структуры данных.
Как отвечать
Начните с того, что данные это только тело ответа, а контракт шире. Что описывается кроме полей:
- ресурсы и адреса, методы и их смысл: что создаёт, что заменяет целиком, что правит частично, какие операции безопасно повторять;
- коды ответов для каждого сценария и единый формат ошибки: машинный код, текст, поле, к которому ошибка относится;
- правила по каждому полю: тип, обязательность, длина, формат даты и часовой пояс, единицы измерения, допустимые значения, поведение при неизвестных полях;
- права: кто вызывает метод, какие поля видит и меняет каждая роль;
- поведение списков: пагинация, сортировка, фильтры, ограничение размера выборки;
- повторы и гонки: ключ идемпотентности, условное обновление по версии записи;
- версионирование и правила совместимости, что считается ломающим изменением;
- нефункциональное: время ответа, лимиты частоты, размер тела, таймауты, поведение при недоступности смежной системы;
- асинхронные операции: приём задачи, опрос статуса, уведомления и повторные доставки.
Хорошая привычка: описание в OpenAPI плюс примеры настоящих запросов и ответов, включая ошибочные. Пример снимает половину вопросов на ревью.
Где спотыкаются
Описывают только счастливый путь. Разработчик придумывает коды и тексты ошибок сам, тестировщик проверяет их по своей фантазии, а клиент получает разное поведение на соседних методах.
Второе: таблица полей без типов, обязательности и форматов. Классические споры отсюда: дата с зоной или без, деньги в копейках или дробным числом, пустая строка против отсутствия поля против null.
Третье: забывают, что список когда-нибудь вырастет. Метод без пагинации и ограничений живёт до первого крупного клиента, а добавить её потом значит сломать совместимость с теми, кто уже интегрировался.