Obsah

Via Aurea Regions API

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.

Historie změn - ZDE Strojová dokumentace API (OpenAPI 3) - ZDE

API umožňuje vyhledávání informací o oblastech a získávání GPS souřanic jejich hranic. API služby je zabezepečeno pomocí nastavení HTTP hlavičky Auth s klíčem projektu získaným z konfigurace projektu na https://services.viaaurea.eu.

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:3018.

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

Simulace produkčního běhu: docker compose -f docker-compose-run.yml up --build → http://localhost:1080

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. Prázdná / nenastavená hodnota = proxy hlavičkám se nedůvěřuje (bezpečný default pro běh bez proxy — jinak by si klient mohl IP podvrhnout).

Struktura

Cesta	Obsah
`public/`	document root — `index.php`, `.htaccess`, statické soubory
`app/`	aplikace (mimo document root)
`lib/`	lokálně držené balíčky bez oficiální podpory (`datto/json-rpc*`)
`docker/`	konfigurace PHP a supervisoru pro image
`tests/`	testy
`doc/api.yml`	OpenAPI 3 specifikace

Popis metod

Vyhledání oblastí a hranic

Pomocí GET požadavku na /area/borders?<query>

Filtry se zadávají jako query GET parametry. Hodnota pole se zadává pomocí oddělení položek čárkou ,.

Povolené filtry a jejich specifikace:

Klíč	Typ	Popis
id	`int`	Vyhledání podle ID oblasti
title	`string`	Vyhledání podle názvu oblasti
code	`string`	Vyhledání podle kódu oblasti. Kraje ČR v NUTS 3 notaci (`CZ011`–`CZ080`), státy dvoupísmenně podle ISO 3166-1 (`GB`, `IS`)
country	`string`	Vyhledání podle kódu státu oblasti - podle ISO 3166-1
winnow	`int`	Číslo 1-n, prosívání souřadnic, vybere se pouze každá n-tá
round	`int`	Číslo 1-n, zaokrouhlení souřadnic na daný počet míst

Alespoň jedna podmínka je povinná!

Informace o oblastech

Pomocí GET požadavku na /area/info?<query> (parametry identické jako v metodě vyhledání)

Zobrazení oblastí

Ukázky získaných dat v Google mapě lze zobrazit na GET požadavku na /area/show?<query> (parametry identické jako v metodě vyhledání)

<query> identické jako v metodě vyhledání