# PDP-API — Changelog

Wszystkie istotne zmiany w API są dokumentowane w tym pliku.

Format opiera się na [Keep a Changelog](https://keepachangelog.com/pl/1.1.0/), wersjonowanie zgodne z [SemVer](https://semver.org/lang/pl/).

## Polityka wersjonowania

- **MAJOR (v1, v2)** — zmiany łamiące zgodność wsteczną (usunięcie pola, zmiana typu, zmiana semantyki). Wprowadzane jako nowa wersja w URL (`/api/v2/...`) z **minimum 90-dniowym okresem przejściowym**.
- **MINOR (1.x.0)** — nowe endpointy, nowe pola, nowe parametry opcjonalne. Wprowadzane bezpośrednio w bieżącej wersji głównej.
- **PATCH (1.0.x)** — poprawki błędów, ulepszenia opisów, optymalizacje wydajności bez wpływu na kontrakt.

Zmiany łamiące są zawsze ogłaszane integratorom mailowo z **minimum 30 dni** wyprzedzenia. Pola oznaczone `[DEPRECATED]` w specyfikacji OpenAPI są przeznaczone do usunięcia w następnej wersji MAJOR.

---

## [Unreleased]

## [1.1.1] — 2026-05-05

### Poprawione
- **Świeżość danych w `/api/v1/operations[/shortened]`** — naprawiono błąd, w którym warstwa cache nie była inwalidowana przy aktualizacji danych operacyjnych. Odpowiedzi są teraz zawsze spójne z bieżącą wersją danych zwracaną przez `/api/v1/data-version`.
- **Planowe czasy (`plannedArrival`/`plannedDeparture`)** — poprawiono błąd, w którym dla pociągów odwiedzających tę samą stację dwukrotnie (np. trasy okrężne) drugie wystąpienie stacji otrzymywało czasy planowe z pierwszego. Teraz każde wystąpienie otrzymuje właściwe czasy zgodne z `plannedSequenceNumber`.

### Dodane
- **Nagłówek `X-Snapshot-Timestamp`** — odpowiedzi z `/api/v1/operations[/shortened]` zawierają nagłówek HTTP z timestampem wygenerowania snapshotu (format ISO 8601). Pozwala konsumentom wykrywać przeterminowane odpowiedzi bez parsowania ciała.
- **Walidacja parametru `pageSize`** — wartości spoza zakresu 1–10 000 są odrzucane z kodem HTTP 400.

## [1.1.0] — 2026-04-28

### Dodane
- **`GET /api/v1/dictionaries/cities`** — endpoint słownika miast z liczbą stacji per miasto i listą identyfikatorów stacji. Pozwala na wyszukiwanie rozkładów na poziomie aglomeracji.
- **`GET /api/v1/disruptions[/shortened]`** — parametr `dictionaries` (bool, domyślnie `true`). Pozwala wyłączyć dołączanie słowników w odpowiedzi i zmniejszyć transfer.
- **Pola `plannedArrival` i `plannedDeparture`** w danych wykonania pociągu — planowe czasy przyjazdu/odjazdu jako `date-time`, spójne z formatem pól `actualArrival`/`actualDeparture`.
- **Nagłówki `X-RateLimit-*`** — opisane w specyfikacji OpenAPI dla operacji wymagających autoryzacji (`X-RateLimit-Hourly-Limit`, `X-RateLimit-Hourly-Remaining`, `X-RateLimit-Daily-Limit`, `X-RateLimit-Daily-Remaining`).
- **Opisy pól** w specyfikacji OpenAPI — kluczowe identyfikatory i pola połączeń opatrzone opisami semantyki.
- **Sekcja "Wersjonowanie i changelog"** w dokumentacji opisowej (`/api-documentation`).

### Zmienione
- **`GET /api/v1/dictionaries/stations`** — maksymalny rozmiar strony (`pageSize`) zwiększony do **10 000**. Pozwala pobrać kompletną listę stacji w jednym żądaniu.
- **Pola `plannedArrival` / `plannedDeparture`** — zmiana formatu z `date-span` na `date-time`. **Zmiana łamiąca** dla klientów parsujących te pola jako czas trwania — patrz „Wycofane" niżej.
- **`/api-documentation`** — zaktualizowane przykłady formatu odpowiedzi i błędów.

### Wycofane (deprecated)
- **Pola `plannedArrivalTime` i `plannedDepartureTime`** (format `date-span`) — pola przejściowe zachowane dla kompatybilności z klientami sprzed v1.1.0. Zostaną usunięte w **v2.0**. Nowi klienci powinni używać `plannedArrival`/`plannedDeparture`.

### Usunięte
- **`/api/diagnostics/health`** i **`/api/diagnostics/import-info`** — usunięte z dokumentacji. Endpointy nie były dostępne.

---

## [1.0.0] — 2026-04-27

Wersja bazowa — patrz specyfikacja OpenAPI

---

## Mapowanie zmian od 2026-03-02 do 2026-04-27 (regresja)

W okresie pomiędzy 2026-03-02 a 2026-04-27 specyfikacja API tymczasowo zawierała funkcje, które następnie zostały wycofane bez ogłoszenia. Lista wycofań:

| Funkcja | Wycofanie | Status w v1.1.0 |
|---------|-----------|------------------|
| `GET /api/v1/dictionaries/cities` | 2026-04-27 | ✅ Przywrócony |
| `pageSize` na `/dictionaries/stations` (max 5000) | 2026-04-27 | ✅ Przywrócony, max **10 000** |
| Parametr `dictionaries` na `/disruptions[/shortened]` | 2026-04-27 | ✅ Przywrócony |
| Pola `isRelated` / `posterNotes` w trasach | 2026-04-27 | ⏳ Planowane przywrócenie w 1.2.0 |

Procedura zapobiegająca podobnym regresjom: każda zmiana usuwająca element z kontraktu wymaga eskalacji + 90-dniowego okresu przejściowego (patrz "Polityka wersjonowania" wyżej).