Przejdź do głównej zawartości

Zapytania różnicowe (since / If-Modified-Since)

Endpointy /api/v1/tariffs, /api/v1/tariffs/components i /api/v1/prices wspierają filtrowanie po czasie ostatniej modyfikacji — przydatne, jeśli budujesz klienta, który odpytuje SENS cyklicznie (polling) zamiast pobierać cały zbiór danych za każdym razem.

Dlaczego to ma znaczenie​

Bez filtrowania różnicowego każdy poll pobiera pełny katalog (setki taryf), nawet jeśli nic się nie zmieniło od ostatniego zapytania. To niepotrzebnie zużywa transfer, czas CPU po obu stronach oraz — w przypadku klientów opartych o LLM/agentów AI — tokeny kontekstu. since pozwala pytać wyłącznie o zmiany.

Parametr since (query param)​

Znacznik czasu ISO-8601 (UTC) lub sama data:

curl -s "https://api.getsens.energy/api/v1/tariffs?since=2026-08-20T12:00:00Z" \
  -H "X-API-KEY: $SENS_API_KEY"

# lub samą datą (interpretowana jako początek dnia UTC)
curl -s "https://api.getsens.energy/api/v1/tariffs?since=2026-08-20" \
  -H "X-API-KEY: $SENS_API_KEY"

Jeśli nic nie zmieniło się od podanego znacznika czasu, odpowiedź to 200 OK z pustą listą ("data": []).

Nagłówek If-Modified-Since​

Standardowy warunkowy nagłówek HTTP — pozwala na klasyczne cache'owanie zamiast ręcznego zarządzania znacznikiem czasu:

curl -s "https://api.getsens.energy/api/v1/tariffs" \
  -H "X-API-KEY: $SENS_API_KEY" \
  -H "If-Modified-Since: Thu, 20 Aug 2026 12:00:00 GMT"

Jeśli nic się nie zmieniło, API zwraca 304 Not Modified (bez treści) — zamiast pustej listy JSON, jak w przypadku since. Każda odpowiedź niosie też nagłówek Last-Modified, który możesz zapisać i przekazać w kolejnym zapytaniu.

Nieprawidłowy format​

Błędnie sformatowany since zwraca 400 Bad Request:

{
  "error": "invalid_parameter",
  "message": "Invalid 'since' timestamp format. Expected ISO-8601 (e.g. 2026-08-20T12:00:00Z) or YYYY-MM-DD."
}

Źródło znacznika czasu​

Pole updated_at w odpowiedzi (dla /prices — meta.last_updated_at) to autorytatywny znacznik ostatniej modyfikacji rekordu — filtruj/porównuj względem niego, nie względem czasu pobrania danych.

Zobacz też​