...

Tieto oblasti REST API rozhrania sú popísané v nasledujúcich kapitolách.

Autentifikácia

Ako už bolo spomenuté v kapitole Ďalšie funkcie SmartWeb platformy, podporovaný spôsob Podporované spôsoby autentifikácie pre REST API je sú HTTP-BASIC a Api Keys.

Pre HTTP-BASIC . Tento typ autentifikácie sa posiela používateľské meno a heslo priamo v hlavičke každej HTTP požiadavky. To znamená že každý REST API request automaticky aj autentifikuje používateľa. V prípade neúspešnej autentifikácie server vracia v hlavičke odpovede HTTP  status 404. Z tohto dôvodu nie je potrebné mať explicitné prihlasovanie do REST API rozhrania cez špeciálnu URL. Napriek tomu je optimálne tú funkciu extrahovať, kvôli aplikáciám v ktorých sa používatelia explicitne prihlasujú a teda aplikácia potrebuje overiť zadané overiť zadané meno a heslo.

Overenie úspešnosti autentifikácie je teda možné odoslaním prázdnej GET požiadavky s HTTP-BASIC autentifikáciou na adresu:

GET https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/auth/login

Odhlásenie sa realizuje odoslaním prázdnej GET požiadavky s HTTP-BASIC autentifikáciou na adresu:

GET https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/auth/logout

Načítavanie hodnôt z archívu

Načítavanie hodnôt z archívu je možné cez GET požiadavku s HTTP hlavičkou Content-Type: application/json na adresu:

Pre Api Keys typ autentifikácie sa v HTTP hlavičke "X-API-Key" posiela aplikačný kľuč - vygenerovaný náhodný reťazec, prostredníctvom ktorého je možné sa autentifikovať. Vyhodou tohto spôsobu autentifikácie je, že sa neposiela meno a heslo do D2000 priamo v requeste. Smart Web aplikácia má tento reťazec vo svojej konfigurácii spárovaný s použivateľskym menom a heslom do D2000. Prihlasovacie údaje ako aj aplikačný kľuč sú bezpečne uložené v špeciálnom keystore na disku, vedľa konfiguračného súboru smartweb.json. Správu týchto kľučov je možné editovať cez Smart Web admin konzolu (web aplikáciu) dostupnú na URL: https://<doména.sk>/<názov aplikácie>/admin.

Overenie úspešnosti autentifikácie je možné spraviť aj samostatne odoslaním prázdnej GET požiadavky s HTTP-BASIC alebo Api Keys autentifikáciou na adresu:

GET https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/auth/login

Taktiež odhlásenie je možné realizovať odoslaním prázdnej GET požiadavky s HTTP-BASIC autentifikáciou na adresu:

GET POST https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/archive/<meno archívneho objektu>?beginTime=<celé číslo>&endTime=<celé číslo>&oversampleSeconds=<celé číslo>&limitDataLength=<celé číslo>returnFields=<text>

Význam jednotlivých parametrov je nasledovný:

...

text (definované Unival atribúty oddelené čiarkou )

...

auth/logout

Načítavanie hodnôt z archívu

Načítavanie hodnôt z archívu je možné cez GET požiadavku s HTTP hlavičkou Content-Type: application/json na adresu:

GET https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/archive/<meno archívneho objektu>?beginTime=<celé číslo>&endTime=<celé číslo>&oversampleSeconds=<celé číslo>&limitDataLength=<celé číslo>returnFields=<text>

Význam jednotlivých parametrov je nasledovný:

Napríklad Napríklad pre nasledujúce HTTP GET volanie:

...

Každá archívna hodnota je reprezentovaná kvôli veľkosti prenášanej správy samostatným poľom, pričom prvý prvok poľa je vždy časová známka a druhý samotná hodnota. V prípade definovania ďalších návratových polí parametrom returnFields sú tieto parametre vrátené v ďalších prvkoch poľa podľa poradia ako boli definované.

Volanie D2000 RPC metód

Načítavanie hodnôt EDA vektora

V prípade ak je nakonfigurované spojenie na EDA server, dá sa realizovať načitavanie a zápis hodnôt do EDA vektorov.

Načítavanie hodnôt EDA vektora je možné cez GET požiadavku s HTTP hlavičkou Content-Type: application/json na adresu:

GET https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/eda/<kód eda vektora>?beginTime=<celé číslo>&endTime=<celé číslo>&period=<text>

Význam jednotlivých parametrov je nasledovný:

Napríklad pre nasledujúce HTTP GET volanie:

GET http://localhost/smartWeb/api/rest/v0/d2/eda/testvektor?beginTime=1633337999000&endTime=1633339999000

dostaneme zo servera odpoveď s poľom archívnych hodnôt:

{
	"errorCode": "SUCCESS",
	"profilingInfo": {
		"numDbTaskRequests": 1,
		"numDbAccesses": 3
	},
	"values": [
		{
			"status": [
				"Valid"
			],
			"value": 999.9,
			"time": 1633338999000
		},
		{
			"status": [
				"Valid"
			],
			"value": 100.1,
			"time": 1633339000000
		}
	]
}

Atribút errorCode identifikuje stav odpovede z EDA servera. Možné hodnoty sú SUCCESS alebo chybové stavy EDA servera: ERR_INTERNAL_ERROR, ERR_INVALID_PARAM_TYPE, ERR_TIMESTEP, ERR_INVALID_VALUE_TYPE, ERR_DB_ERROR, ERR_VECTOR_NOT_EXIST, ERR_INVALID_VECTOR_TYPE, ERR_LOGON, ERR_VECTOR_NAME, ERR_CONVERT_ERROR, ERR_NOT_IMPLEMENTED, ERR_RANGE_ERROR, ERR_VALUE_STATUS, ERR_END_WITHOUT_RETURN, ERR_SYNTAX_ERROR, ERR_EMPTY_SET_OF_VECTORS, ERR_CACHE_NOT_FOUND, ERR_CACHE_READ_CHANGED, ERR_CACHE_TOO_MANY_READS, ERR_CACHE_READ_WRITE_MISMATCH, ERR_CACHE_RECURSIVE_VECTOR_DEFINITION, ERR_CACHE_NO_MEMORY, ERR_TBLSPACE_NOT_EXIST, ERR_TIMESTEP_FOR_TBLSPACE, ERR_TBLSPACE_ALLREADY_EXIST, ERR_INSUFFICIENT_RIGHTS, ERR_CANCELED, ERR_VERSION_DOESNT_EXIST, ERR_NOT_ARCHIVED, ERR_ARCHIVE_ERROR, ERR_VECTOR_ALREADY_EXISTS, ERR_VERSION_ALREADY_EXISTS, ERR_ENV_DOESNT_EXIST, ERR_BATCH_DOESNT_EXIST, ERR_BATCH_ALREADY_RUNNING, ERR_BATCH_TOO_MANY_BATCHES, ERR_OUT_OF_MEMORY, ERR_PARAM_BLOCK_DOESNT_EXIST, ERR_PARAM_BLOCK_TOO_MANY, ERR_VALIDATION_FAILED.

Atribút profilingInfo uvádza profilovacie informácie o obsluhe požiadavky. V atribúte values sa nachádzajú hodnoty EDA vektora za daný interval.

Zápis hodnôt do EDA vektora

Zápis hodnôt EDA vektora je možné realizovať cez POST požiadavku s HTTP hlavičkou Content-Type: application/json na adresu:

POST https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/eda/<kód eda vektora>

Napríklad pre nasledujúce HTTP POST volanie s nasledujúcim obsahom POST requestu, zapíšeme hodnoty do EDA vektora:

POST http://localhost/smartWeb/api/rest/v0/d2/eda/testvektor

{
	"values":[
		{
			"value":999.9,
			"time":1633338999000,
			"status":["Valid"]
		},
		... <dalsie hodnoty>
	]
}

odpoveď na zápis môže byť nasledovná

{
	"errorCode": "SUCCESS",
	"profilingInfo": {
		"numDbTaskRequests": 2,
		"numDbAccesses": 12
	}
}

Atribút errorCode identifikuje stav odpovede z EDA servera. Možné hodnoty sú uvedené v predchádzajúcej podkapitole.

Volanie D2000 RPC metód

Cez REST rozhranie je možné volať D2000 RPC procedúry napísané v ESL aj v Jave. Volanie ESL RPC procedúr prebieha odoslaním POST požiadavky s HTTP hlavičkou Content-Type: application/json na jednu z adries:

POST https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/rpc/<meno eventu>/<meno RPC metódy>

POST https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/rpc/interface/<meno eventu>/<meno interfacu>/<meno RPC metódy>

 v prípade volania Java RPC su URL nasledovné:

POST https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/rpc/java/<meno eventu>/<meno RPC metódy>

POST https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/rpc/java/interface/<meno eventu>/<meno interfacu>/<meno RPC metódy>

Ak chceme volat RPC metodu smeno procesu namiesto mena eventu je možné použiť nasledovné URL adresyCez REST rozhranie je možné volať D2000 RPC procedúry napísané v ESL aj v Jave. Volanie ESL RPC procedúr prebieha odoslaním POST požiadavky s HTTP hlavičkou Content-Type: application/json na adresu:

POST https://<doména<doména.sk>sk>/<názov aplikácie>/api/rest/v0/d2/rpc/japi/<meno eventu>procesu>/<meno RPC metódy> v prípade volania Java RPC je URL nasledovná:

POST https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/rpc/java/japi/interface/<meno procesu>/<meno eventu>interfacu>/<meno RPC metódy>

Telo odosielanej správy je JSON pole s parametrami volanej RPC. Výstupom takejto požiadavky sú hodnoty výstupných parametrov RPC uložené v JSON objekte, ktorého atribúty sú požadované názvy výstupných parametrov definované atribútmi returnAs. Detaily serializácie parametrov RPC metód boli popísaná v predchádzajúcej kapitole. Príklad volania RPC s názvom TestInOut na evente E.E.SmartWebApiTutorial s 5 parametrami, pričom prvý, tretí a štvrtý parameter sú vstupno-výstupné a definujú logický názov pre vracané hodnoty parametrov. Vstupné parametre (druhý a piaty) zároveň využívajú implicitnú konverziu na Unival objekt z jednoduchých JSON typov.

...

Nasledujúci príklad ilustruje volanie a implementaciu SBA RPC metódy pre stahovanie konkrétneho súboru pdf reportu z lokálneho súborového systému. Pozor uvedený príklad nie je vôbec vhodný pre reálne použítie a je uvedený iba pre ilustráciu použitia volania SBA RPC. Volanie SBA RPC metódy reportContract_PDF v evente E.E.SmartWebApiTutorial s parametrom id ktorý identifikuje číslo reportu a tým pádom sťahovaného súboru.

GET http://localhost/smartWebsmartweb/api/rest/v0/d2/sba/E.E.SmartWebApiTutorial/reportContract_PDF?fileName=report.pdf&id=10

...