Obsah

VA service Exchange rates

demo

Verze pro PHP 8.5.x a Kubernetes. Služba běží v kontejneru z base image docker/php-8/8.5:latest-skeletnext-regular. Starší verze na PHP 7.4 nasazovaná přes tools/deployment je na větvi master.

VA služba pro získávání a přepočet měnových kurzů vůči domácí měně - Česká koruna CZK - historie změn

Strojová dokumentace API (OpenAPI 3) - ZDE

Vývoj

Veškerá práce probíhá v kontejneru — obsahuje PHP 8.5 se všemi potřebnými extensions.

cp docker-compose.override.yml.example docker-compose.override.yml
docker compose up -d
docker compose exec php composer install

Služba pak běží na http://localhost:3868.

Příkaz Co dělá
docker compose exec php composer test testy (nette/tester)
docker compose exec php composer phpstan statická analýza (level 5 + baseline)
docker compose exec php composer rector návrh refaktoringu na PHP 8.5 (dry-run)
docker compose exec php composer lint:cs kontrola PSR-12
docker compose exec php composer import ruční import kurzů z ČNB

Simulace produkčního běhu: docker compose -f docker-compose-run.yml up --build

Nasazení za reverzní proxy / k8s ingress

Za proxy je REMOTE_ADDR adresa proxy, ne klienta — kontrola IP i logování by pak pracovaly se špatnou hodnotou a všechny požadavky by vypadaly, že jdou z jedné adresy.

Proto je potřeba nastavit proměnnou TRUSTED_PROXIES na rozsah, ze kterého proxy chodí:

TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

Teprve pak služba čte skutečnou IP klienta z hlavičky X-Forwarded-For.

Import kurzů

bin/importExchangeRates [dateFrom] [dateTo] stahuje kurzovní lístek ČNB.

Je to periodická úloha a musí ji něco pravidelně spouštět, jinak se kurzy přestanou aktualizovat. Ručně ji lze vyvolat i přes API metodu 4 (/api/import).

Pozn.: ČNB publikuje lístek kolem 14:30. Dotaz na dnešek před tím vrátí poslední starší lístek — služba to řeší dohledáváním nejbližšího staršího kurzu.

API metody

1. GET /api/rate - vyhledá kurz pro měnu a datum

Vyhledá kurz na zadanou měnu a den. Pokud není kurz dostupný pro daný den, vrátí nejbližší starší do max. tolerance (3 měsíce).

Query parametry:

Příklady:

Odpověď je JSON ve tvaru:

{
   "found": true,
   "date_requested": "2021-02-14",
   "currency": "USD",
   "date": "2021-02-10",
   "amount": 1,
   "rate": 21.301
}

Pozn.:

Odpověď HTTP 404 v případě NEnalezení záznamu:

{
    "found": false,
    "date_requested": "2004-01-01",
    "currency": "USD"
}

2. GET /api/rates - vyhledá všechny kurzy pro datum

Vyhledá nejbližší kurzy (stejná logika jako u 1.) na zadaný den pro všechny dostupné měny

Query parametry:

Příklady:

Tvar odpovědi, záznamy se sloučí do struktury [currency]{item}

{
    "count": 3,
    "date_requested": "2018-03-01",
    "items": {
        "EUR": {
            "date": "2018-03-01",
            "currency": "EUR",
            "amount": 1,
            "rate": 25.435
        },
        "GBP": {
            "date": "2018-03-01",
            "currency": "GBP",
            "amount": 1,
            "rate": 28.735
        },
        ...
    }
}

3. GET /api/rates-history - prohledá historii kurzů

Vyhledá kurzy v rozsahu zadaných datumů pro měny - vrací pouze reálně nalezené položky (dny, které nemají kurz se nevrací!)

Route parametry:

Query parametry:

Příklady:

Tvar odpovědi, group=none:

{
    "limit": 365,
    "page": 1,
    "num_pages": 1,
    "count": 3,
    "total": 3,
    "date_from_requested": "2021-02-12",
    "date_to_requested": "2021-02-16",
    "items": [
        {
            "date": "2021-02-16",
            "currency": "EUR",
            "amount": 1,
            "rate": 25.755
        },
        {
            "date": "2021-02-15",
            "currency": "EUR",
            "amount": 1,
            "rate": 25.68
        },
        ...
    ]
}

Tvar odpovědi, group=currency:

{
    ...
    "date_from_requested": "2020-12-29",
    "date_to_requested": "2021-02-17",
    "items": {
        "EUR": [
            {
                "date": "2021-02-16",
                "currency": "EUR",
                "amount": 1,
                "rate": 25.755
            },
            ...
        ],
        "GBP": [
            {
                "date": "2021-02-16",
                "currency": "GBP",
                "amount": 1,
                "rate": 29.493
            },
            ...
        ],
        ...
    }
}

Tvar odpovědi, group=date:

{
    ...
    "date_from_requested": "2018-01-01",
    "date_to_requested": "2018-12-31",
    "items": {
        "2018-12-31": [
            {
                "date": "2018-12-31",
                "currency": "EUR",
                "amount": 1,
                "rate": 25.725
            },
            ...
        ],
        "2018-12-28": [
            {
                "date": "2018-12-28",
                "currency": "EUR",
                "amount": 1,
                "rate": 25.78
            },
            ...
        ],
        ...
    }
}

4. GET /api/import - import kurzů z ČNB

Stáhne kurzovní lístek ČNB a uloží ho do databáze. Běžně se spouští periodicky, tento endpoint slouží k ručnímu vyvolání.

Query parametry:

Odpověď: {"status": "ok"}

Tak co, pomohla ti DOCka? Nebo by chtěla opravit?

Like Revize Read