Dadata Proxy

Это Self-Hosted приложение, которое проксирует clean запросы к datdata.ru и кеширует ответы на время, которым вы сами можете управлять.

Интерфейс API полностью повторяет интерфейс API dadata.ru, и вам потребуется изменить BASE_URL в \Dadata\CleanClient и всё будет работать, как будто и нет никого между вами. Как это сделать — читайте далее.

Использование этого прокси позволяет экономить на платных запросах, например к clean/name или clean/phone.

Допустим, приложение нормализовало имя иванов иван иванович, заплатив за это копеечку. В следующий раз оно нормализует это же имя, но уже бесплатно, потому что получит ранее сохраненный ответ.

N.B.
Теоретически, если все будут проксировать свои запросы через один прокси, то Dadata недополучит кучу денег. Это является воровством и мы настаиваем, чтобы вы так не делали! Не рубите сук, на котором сидите. Без Dadata мир станет совсем уж мрачным местом.

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

Управление кешированием

Если сделать запрос, как он описан в документации dadata, то ответ будет закеширован прокси и впредь будет возвращаться из кеша, без запросов к dadata.

Но например, если в запросе передать заголовок Cache-Control с параметром max-age (в секундах), то ответ из кеша будет использован только если он не старше указанного возраста. В противном случае будет выполнен запрос к dadata и кеш будет обновлён свежим ответом.

POST /api/v1/clean/name HTTP/1.1
Host: example.com
Content-Type: application/json
Accept: application/json
Authorization: Token {token}
X-Secret: {secret}
Cache-Control: max-age=600

["иванов иван иванович"]

Поддерживаемые инструкции Cache-Control в запросе:

max-age=<seconds>

Задаёт максимальное время в течение которого ресурс будет считаться актуальным.

Если локальный кеш старше указанного значения, то будет выполнен запрос к dadata, и ответ будет обновлен в кеше.

max-stale[=<seconds>]

Указывает, что клиент хочет получить ответ, для которого было превышено время устаревания. Дополнительно может быть указано значение в секундах, указывающее, что ответ не должен быть просрочен более чем на указанное значение.

Инструкция имеет смысл в комбинации с max-age. Например, кеш устарел, но dadata сейчас недоступна и мы не можем получить свежие данные. Значит будем использовать то, что есть в кеше.

Если запрос к dadata не получился, и записей подходящей свежести в кеше нет, то ответ будет [].

min-fresh=<seconds>

Указывает, что клиент хочет получить ответ, который будет актуален как минимум указанное количество секунд.

Инструкция имеет смысл в комбинации с max-age. Например, кеш ещё не устарел, но устареет раньше, чем требует min-fresh. Значит необходимо освежить кеш, сделав запрос в dadata.

no-cache

Указывает на необходимость отправить запрос на сервер для валидации ресурса перед использованием закешированных данных.

Запрос к dadata будет выполнен безусловно, ответ будет закеширован.

no-store

Кеш не должен хранить никакую информацию о запросе и ответе.

Ответ dadata закеширован не будет.

only-if-cached

Указывает на необходимость использования только закешированных данных. Запрос на сервер не должен посылаться.

Запроса к dadata не будет. Будет возвращен ответ из кеша, если он там есть. Если его там нет, то ответ будет [].

Расширение библиотеки dadata

Клиент hflabs/dadata очень тяжело поддаётся изменениям. Атрибуты не определяются через конструктор, большинство приватны. То есть их даже не переопределить при наследовании.

Мы предлагаем расширение codewiser/dadata, которое решает эту проблему. Вообще, это просто обертка вокруг ответов официального клиента. Она превращает массив в хорошо документированный объект. Но также она содержит и официальный клиент с возможностью конфигурирования.

Конфигурирование (в AppServiceProvider::boot())

use Codewiser\Dadata\Client\DadataClient;
use Codewiser\Dadata\Client\CleanClient;

DadataClient::cleanResolver(
    // Сравни с
    // https://github.com/hflabs/dadata-php/blob/master/src/CleanClient.php#L9
    
    fn() => new CleanClient($token, $secret, 'https://my-proxy.ru/api/v1/')
);

Использование клиента:

use Codewiser\Dadata\DaDataService;

$cleanName = app(DaDataService::class)->client
    ->clean('name', 'иванов иван иванович', [
        'Cache-Control' => 'max-age:86400'
    ]);

// Запрос отправлен через https://my-proxy.ru

Кешируемые сервисы

• стандартизация адресов
• стандартизация ФИО
• стандартизация телефонов
• стандартизация паспортов
• стандартизация email
• стандартизация автомобилей

Остальные clean сервисы, ежели такие остались, проксируются без кеширования.