ptServer

PT server

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

• umožnit vzdálenou správu hJOPserveru,
• 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 osttaně 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é.

Funckcionalita

PT server umožňuje toto:

• dotazovat server na data a stav,
  • bloků,
  • hnacích vozidel,
• přestavít výhybku,
• řídit hnací vozidlo na základě adresy.

Technická specifikace

• Se serverem se komunikuje výhradně v kódování UTF-8.
• Server na každý požadavek vrací 200 OK.
• Defaultní port serveru je 5823.
• Chyby při zpracování požadavků jsou zaneseny do odpovědi jako errors objekt. Viz specifikace

JSON data

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

• Blok
• Stanice
• Hnací vozidlo

Endpointy serveru

GET /bloky

• Endpoint vrací bloky.
• Parametry:

• stanice=id – vrací jen bloky v dané stanici,
• typ=typ – vrací jen bloky daného typu,
• stav=True/False – jestli vrátit s bloky i jejich stav.

{
	"bloky": [
		{...}, {...}, ...
	]
}

GET /bloky/id

• Endpoint vrací blok id.
• Parametry:

• stav=True/False – jestli vrátit s bloky i jejich stav.

{
	"blok": {
		...
	}
}

GET /blokStav/id

• Endpoint vrací stav bloku id.
• Parametry: žádné.

{
	"blokStav": {
		...
	}
}

PUT /blokStav/id

• Endpoint umožňuje změnit stav bloku id.
• Odpovědí je nový stav bloku.
• Stav bloku měníme posláním nového kýženého stavu v těle požadavku.

{
	"blokStav": {
		"poloha": "-"
	}
}

TODO: dodělat popis konkrétních požadavků

GET /stanice

• Endpoint vrací seznam stanic.
• Parametry: žádné.

{
	"stanice": [
		{...}, {...}, ...
	]
}

GET /stanice/id

• Endpoint vrací stanici s id id.
• Parametry: žádné.

{
	"stanic": {
		...
	}
}

GET /loko

• Endpoint vrací seznam lokomotiv.
• Parametry:

• aktivni=True/False – jestli vrátit jen aktivní lokomotivy. Pokud není argument přítomný, vrátí všechny loko, pokud je přítomný, vrátí jen aktivní/neaktivní.

{
	"loko": [
		{...}, {...}, ...
	]
}

GET /loko/addr

• Endpoint vrací lokomotivu s adresou addr.
• Parametry: žádné.

{
	"lok": {
		...
	}
}

GET /lokoStav/addr

• Endpoint vrací stav lokomotivy s adresou addr.
• Parametry: žádné.

{
	"lokStav": {
		...
	}
}

PUT /lokoStav/addr

• Endpoint umožňuje změnit stav lokmotivy s adresou addr.
• Odpovědí je nový stav lokomotivy.
• Stav lokomotivy měníme posláním nového kýženého stavu v těle požadavku.
• Kýžený stav se od aktuálního stavu může lišit ve více parametrech, server se v takovém případě pokusí udělat nejlepší možnou akci.

{
	"lokStav": {
		"rychlost": 15
	}
}

TODO: konkrétní změny stavů