Ключ и лимиты

Каждый запрос передаёт ключ в заголовке X-API-Key. Считаются два предела: запросы в секунду и запросы в сутки. На этой странице — как передать ключ, как следить за остатком и как не тратить запросы впустую.

Передайте ключ#

Ключ идёт в заголовке X-API-Key каждого запроса. Во всех примерах документации он берётся из переменной окружения KINODATA_KEY:

curl -H "X-API-Key: $KINODATA_KEY" \
  "https://api.kinodata.space/v1.3/ids/kp/447301"

{
  "imdb_id": "tt1375666",
  "kp_id": "447301",
  "tmdb_id": "27205",
  "tmdb_tv_id": null,
  "kinorium_id": "472809"
}

Без ключа или с неверным ключом API отвечает 401. Тот же запрос без заголовка:

curl -s "https://api.kinodata.space/v1.3/ids/kp/447301"

{
  "error": {
    "code": "unauthorized",
    "message": "missing api key"
  }
}

Без ключа отвечает только https://api.kinodata.space/health — проверка, что API работает.

Пределы тарифов#

На Basic и Business можно выпустить два ключа. Пределы при этом — на аккаунт, а не на ключ: два ключа Basic делят одни 20 запросов в секунду и 5 000 в сутки, а не получают столько каждый.

Сутки считаются по UTC: квота обновляется в полночь по UTC, а не через 24 часа после первого запроса. Тарифы и цены — на странице Тарифы.

Следите за остатком#

С каждым ответом приходят заголовки с текущим остатком:

Так выглядят заголовки ключа Basic:

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 19
X-RateLimit-Reset: 1791566201
X-Quota-Limit: 5000
X-Quota-Remaining: 4812
X-Quota-Reset: 1791590400

У ключа без предела соответствующих заголовков нет. Из браузера они тоже видны: API открывает их в Access-Control-Expose-Headers.

Если упёрлись в предел#

API отвечает 429. Текст ошибки говорит, какой предел сработал:

{
  "error": {
    "code": "rate_limited",
    "message": "quota limit exceeded"
  }
}

• rate limit exceeded — запросов в этой секунде больше, чем разрешено. Подождите Retry-After секунд и разнесите запросы во времени: очередь или пауза между запросами помогут лучше повторов.
• quota limit exceeded — квота на сутки закончилась. Retry-After покажет, сколько секунд до полуночи по UTC. Если квоты не хватает регулярно, посмотрите тарифы.

Запрос, отклонённый пределом в секунду, квоту на сутки не тратит.

Экономьте запросы#

Берите только нужные блоки#

Карточка тайтла целиком весит около 26 КБ. Если нужны название и оценки, попросите только их: fields=title,ratings. Ответ станет меньше, а запрос — дешевле для вашей сети. Подробнее — в разделе Списки и пагинация.

Кэшируйте ответы#

Ответ можно хранить пять минут: API присылает Cache-Control: private, max-age=300. Хранить его может ваш сервер или браузер, но не общий кэш вроде CDN: ответ принадлежит ключу.

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

1. Сохраните заголовок ETag из ответа — здесь в переменную ETAG:

ETAG=$(curl -sI -H "X-API-Key: $KINODATA_KEY" "https://api.kinodata.space/v1.3/titles/tmdb/27205" | grep -i '^etag:' | cut -d' ' -f2 | tr -d '\r')

1. В следующем запросе к тому же адресу передайте его в If-None-Match как есть, вместе с кавычками:

curl -s -o /dev/null -w '%{http_code}\n' -H "X-API-Key: $KINODATA_KEY" -H "If-None-Match: $ETAG" "https://api.kinodata.space/v1.3/titles/tmdb/27205"

Если данные не изменились, придёт 304 без тела — значит, сохранённый ответ ещё верен. Ответ 304 не тратит квоту: проверять свежесть данных так можно сколько угодно часто.

Включите сжатие#

С заголовком Accept-Encoding: gzip карточка «Начала» весит 8 КБ вместо 26 КБ. Большинство HTTP-клиентов просят сжатие сами. curl — только с флагом --compressed.

Храните ключ на сервере#

API отвечает на запросы из браузера с любого сайта, но ключ в коде страницы или мобильного приложения увидит любой, кто откроет инструменты разработчика. Отправляйте запросы со своего сервера, а в браузер отдавайте готовые данные.

Если что-то не так#

С каждым ответом приходят два служебных заголовка:

Дальше#

• Ошибки — все коды и что с ними делать.
• Списки и пагинация — как листать длинные ответы.