Проблема API-ключей, которые никогда не истекают
Ключ, выданный много лет назад, ни разу не заменённый и до сих пор действующий, это не удобство. Это риск, на который никто не смотрел уже много лет.
Против проприетарных форматов ответа
Спросите, почему API возвращает вложенную собственную объектную модель вместо простой плоской структуры JSON, и честный ответ редко окажется техническим. Проприетарная структура не делает запрос быстрее или точнее. Она затрудняет замену ответа, потому что каждое имя поля, каждый уровень вложенности и каждый собственный код статуса, который учится обрабатывать ваш код, становится небольшим фрагментом знаний, специфичных для поставщика и встроенных в ваше приложение.
Мы считаем, что это поставлено с ног на голову. Формат ответа должен описывать данные, а не поставщика. Координаты, адреса, смещения и высоты остаются теми же понятиями независимо от того, кто отвечает на запрос, поэтому возвращаемая для них структура должна быть примерно такой же простой, как сами эти понятия. Именно поэтому 17 наших хостов возвращают точно такую же структуру ответа, как собственный API другого провайдера: данные наши, но структура может быть уже знакома вашему коду, потому что изобретать её, по сути, и не нам.
Проприетарные форматы также склонны накапливать странности, которые не имеют никакого отношения к самим данным и полностью связаны с внутренней историей провайдера. Поле переименовывают ради внутренней миграции, а старое имя остаётся устаревшим псевдонимом, который никто не хочет удалять. Статус в одном эндпоинте представлен строкой, а в другом числовым кодом, потому что их создавали разные команды с разницей в несколько лет. Ничего злонамеренного в этом нет. Так просто происходит, когда формат никогда не проектируется с оглядкой на внешний стандарт, а только на собственную развивающуюся кодовую базу компании.
Решение несложное: выбрать простую структуру, один раз её задокументировать и сохранять стабильной. Мы делаем это во всех наших собственных эндпоинтах и идём на шаг дальше с совместимыми хостами, точно воспроизводя структуру другого провайдера, чтобы кодовой базе, которая уже разбирает эту структуру, не требовалось никаких изменений, кроме базового URL и ключа. Это более серьёзное обязательство, чем может показаться. Оно означает, что если в воспроизводимой нами структуре есть неудобное имя поля или непоследовательная вложенность, мы сохраняем эту неудобность, потому что вся ценность совместимого хоста заключается в точности, а не в улучшениях.
Проприетарный формат иногда защищают тем, что он даёт провайдеру возможность со временем добавлять более богатые данные. Мы не считаем, что для богатства данных нужна незнакомая структура. Необязательные поля, например высота или сведения об IP-угрозах, могут располагаться рядом со стандартным ответом как дополнения, а не замены, так что клиенту, который их не запрашивает, никогда не придётся их обходить при разборе, а клиент, который их запрашивает, получает их без изучения нового формата.
На самом деле всё это не про форматирование JSON как техническое предпочтение. Всё это про то, кто несёт расходы от решения о структуре. Проприетарный формат перекладывает эти расходы на каждого клиента, которому когда-либо придётся читать ответ. Простой или воспроизведённый формат перекладывает их на нас, в виде проектной работы по сохранению предсказуемости. Именно там этим расходам и место.