DISOD API

Jednoduché rozhraní pro vyhledání personálu vlaku. Každé úspěšné vyhledání server automaticky uloží do malé databáze SQLite. Při dalším vyhledání stejného vlaku se aktuální výsledek vrátí společně s jeho historií.

Rychlý příklad

Chcete-li vyhledat vlak číslo 351, pošlete serveru požadavek:

curl -X POST https://zvonek-9316.rostiapp.cz/api/train -H "Content-Type: application/json" -d '{"train":"351"}'

Odpověď obsahuje údaje o vlaku, aktuální a odstoupený personál a také pole history s předchozími vyhledáními.

Dostupné adresy

POST `/api/train`

Vyhledá vlak podle jeho čísla. Číslo musí obsahovat pouze číslice. Server se dotáže služby DISOD, výsledek uloží do SQLite databáze a vrátí ho spolu s historií stejného vlaku.

Co poslat

Tělo požadavku musí být ve formátu JSON a obsahovat položku train:

{
  "train": "351"
}

Co dostanete zpět

Odpověď obsahuje zejména:

found – zda byl vlak nalezen,
train – základní údaje o vlaku,
current – aktuálně přiřazený personál,
retired – odstoupený nebo historický personál,
retrieved_at – přesný čas načtení výsledku,
history – dříve uložené výsledky stejného vlaku.

Historie vyhledávání

Každá položka v history obsahuje přesný čas searched_at a uložený výsledek v položce result. Čas je uložen v UTC ve formátu ISO 8601.

Možné chyby

400 – číslo vlaku chybí nebo není platné,
500 – chybí certifikát, klíč nebo se nepodařilo uložit výsledek,
502 – problém při komunikaci se službou DISOD,
504 – služba DISOD neodpověděla včas.

GET `/api/train/<číslo>/history`

Vrátí pouze uloženou historii konkrétního vlaku. Tento požadavek se znovu nedotazuje služby DISOD.

Příklad:

curl https://zvonek-9316.rostiapp.cz/api/train/351/history

GET `/api/health`

Ověří, zda aplikace běží, zda jsou dostupné klientské certifikáty a zda server vidí databázový soubor.

Příklad:

curl https://zvonek-9316.rostiapp.cz/api/health

GET `/api/docs`

Zobrazí tuto dokumentaci v podobě běžné webové stránky. Dokumentace už není vracena jako JSON.

Význam kódů funkcí

0 – Vlakvedoucí
1 – Průvodčí
6 – Strojvedoucí

Pokud DISOD vrátí neznámý kód, server ho nezahodí. V aplikaci se zobrazí jako „Neznámá funkce (kód X)“.

Ukládání historie

Historie se ukládá do souboru: /srv/app/disod_history.sqlite3

Databáze používá SQLite, takže není potřeba instalovat samostatný databázový server. Při každém novém vyhledání se vytvoří nový historický záznam; starší záznamy se nepřepisují.

Historie se řadí od nejnovějšího vyhledání po nejstarší.