ptServer

PT server v3.1

PT server je http server implementující REST API. Jeho účel je

• umožnit vzdálenou správu hJOPserveru,
• umožnit komunikaci s hJOP pro externí řízení kolejiště,
• poskytnout rozhraní k řízení kolejiště pro studenty MENDELU.

S PT serverem se komunikuje ve formátu JSON. Veškerá dokumentace, jména endpointů, atributů a ostatně všeho jsou v češtině.

PT server je zakompilovaný v základní verzi hJOPserveru, avšak automaticky se nespouští. PT server nevyžaduje žádnou autentizaci, což by mělo být, vzhledem k vypnutému serveru by default, únosně bezpečné.

Funkcionalita

PT server umožňuje toto:

• dotazovat server na data a stav bloků, hv, jc, ...,
• přestavit výhybky,
• řídit hnací vozidlo na základě adresy,
• stavět jízdní cesty.

Technická specifikace

• Se serverem se komunikuje výhradně v kódování UTF-8.
• Server na každý požadavek vrací 200 OK.
  • Výjimka: neautentizovaný požadavek (vrací se kód 401).
• Výchozí port serveru je 5823.
• Chyby při zpracování požadavků jsou zaneseny do odpovědi jako errors objekt. Viz specifikace
• Při požadavcích, které obsahují tělo (PUT, POST, ...), je nutné nastavit hlavičku Content-type na hodnotu application/json. Požadavek s jiným Content-type nebude zpracován.
• Požadavky nesmí obsahovat UTF-8 BOM. Odpovědi serveru neobsahují UTF-8 BOM.

Autentizace (od verze 2)

• Všechny GET požadavky je možné odesílat bez autentizace, všechny PUT, POST a DELETE požadavky vyžadují autentizaci.
• Pro autentizaci je využíván http simple auth.
• Klient má své uživatelské jméno a heslo. Tyto údaje zřetězí pomocí dvojtečky (login:password), zakóduje výsledný řetězec do base64 a pošle v hlavičce Authorization takto: Basic <base64-encoded-string>.

JSON data

Následující stránky obsahují specifikace objektů posílaných v požadavcích a odpovědích.

• Blok
• Hnací vozidlo
• Jízdní cesta
• Souprava

Obecné poznámky

Kdykoliv je v GET parametru předáván argument typu Boolean, může parametr nabývat hodnot:

• true/false v jakékoliv velikosti písmen (napr. tRue je také validní), nebo
• 0/1.

Konfigurace serveru

PTserver má záznam v konfiguračním souboru data/konfigurace.ini:

[PTServer]
port=5823
compact=0

U serveru je možné změnit jeho port a jestli mají být odpovědi serveru kompaktní.

Endpointy serveru

• Blok
• Hnací vozidlo
• Jízdní cesta
• Souprava
• Uživatel
• Oblast řízení
• Stav

Historie revizí

• v1.0: první verze PT serveru
• v1.1: sekce mtb nahrazena sekcí rcs
• v1.2: odstraněno API stanic, přidáno API jízdních cest
• v2.0: přidána (povinná) autentizace uživatelů
• v2.1: přidáno API souprav
• v2.2: přidáno API uživatelů, umožněno PUT, DELETE a POST API souprav
• v3.0: data všech endpointů převedena do angličtiny, přidán endpoint oblasti řízení.
• v3.1: přidán endpoint status