На работе при обсуждении стороннего API возник спор (на мой взгляд, на ровном месте): а нужно ли выносить в ответ сервера коды состояния. Собственно обсуждали три варианта ответа сервера, и выбирали, какой из них более правильный:
1. "status": "в работе"
2. "status_code": 4, "status_name": "в работе"
3. "status": { "code": 4, "name": "в работе" }
Попробую вкратце показать подводные камни и недостатки каждого варианта. Начну собственно с замечания, что при проектировании API (да, API тоже нужно проектировать), действуют те же принципы, что и при написании программ: DRY, KISS, YAGNI, инкапсуляция и даже чистый код вполне уместен.
Можно ли использовать сразу status_code и status_name?
Не нужно, ибо это сразу вызывает вопросы. Я, как сторонний разработчик, сразу оказываюсь в глупом положении. У меня куча вопросов на ровном месте. Эти две переменных – одно и то же? А если нет? Какую переменную мне лучше использовать? Или сразу обе? А возможна ситуация когда я получу два ответа сервера
"status_code": 4, "status_name": "в работе"
и
"status_code": 1, "status_name": "в работе"
Это будет ошибка? Или как? Без подробного изучения документации у меня нет на это ответов. KISS.
Скорее всего, при создании API использовалась таблица из БД, где хранились коды статусов. Собственно в этом нет ничего страшного – стандартная практика. Однако, предположим, что наше приложение стало мегопопулярным и количество запросов на наш API выросло в тысячу раз. К нам приходит тимлид и говорит – оптимизируйте код, лишние запросы к БД нам не нужны. В итоге статусы у нас теперь хранятся в массиве или в строчной переменной, и второй столбец (ID или NAME, на ваш вкус) потерял всякий смысл – но из-за обратной совместимости API должно его возвращать. Вот зачем вам это?
Это лишь пара примеров, когда повторение информации губительно сказывается на качестве конечного продукта. Опытные программисты, уверен, найдут более животрепещущие варианты. DRY.
status_code vs status_name
Начну опять с жизненного примера. Один из моих модулей сейчас работает с API российского сервиса DaData. Из саппорта приходит задача: «адрес не распознался». Я лезу в логи и вижу ответ DaData:
"qc": 3
Что это значит? Вы знаете? И я не знаю. Я вынужден лезть на сайт DaData, искать там документацию, искать нужный раздел документации, нужную главу с маршрутом, нужный мне параметр qc и его описание. «У адреса есть альтернативные варианты». А сразу нельзя было сказать? Вы тратите мое время, меня это печалит. Кстати, QC, скорее всего, расшифровывается как quality code, но это не точно.
Следующий пример. Кодированный ответ потенциально портит код, в котором вынужденно появляются конструкции вида:
const STATUS_IN_WORK = 4;
...
if ($status == self:: STATUS_IN_WORK)
сравните:
if ($status == 'in_work')
Вот дались вам эти цифры. Вы их складывать собираетесь? Или умножать? Ответ сервера должен читаться без документации.
В качестве бонуса
Меня немного удивляет упорность с которой русскоязычные программисты пихают в код русские слова. Вот зачем? Я пишу и читаю код на PHP, это текст на английском языке. И тут в нем 'в работе'. Мне реально бывает надо несколько мгновений, что бы переключиться и перевести это в 'in_work', сравните:
if ($status == 'in_work')
// vs
if ($status == 'в работе')
Для наглядности то же самое в 1С:
Если статус = "in_work" Тогда
// vs
Если статус = "в работе" Тогда
Резюме
Если вы пишите API для 1C – вполне возможен вариант
"status": "в работе"
В остальных случаях лучше
"status": "in_work"
PS Для тех, кому интересна эта тема, могу порекомендовать хорошую книгу Арно Лоре "Проектирование веб-API".
UPD: В продолжение темы - "Re: Нужны ли в API цифровые коды?".