REST API rozhranie implementované Smart Web SmartWeb platformou môžeme rozdeliť na nasledovné časti:

rozhranie na autentifikáciu
rozhranie na prístup k dátam a službám D2000 systému
administrátorské rozhranie na monitorovanie volaní do D2000 a stavu Smart Web SmartWeb servera

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

Obsah

Autentifikácia

Ako už bolo spomenuté v kapitole Ďalšie funkcie Smart Web 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

Info
Volanie explicitného odhlásenie je odporúčané z dôvodov že Smart Web server udržuje session prihláseného používateľa REST služby (identifikovaného jeho prihlasovacím menom) až do expirácie sedenia konfigurovateľnej v autentifikačnej časti konfigurácie Smart Web Platformy.

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:

POST 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>/apiadmin.

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/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/login

Taktiež odhlásenie je možné realizovať 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

Info

Volanie explicitného prihlásenia a odhlásenia nie je nevyhnutné, pretože autentifikačné údaje (HTTP BASIC alebo Api Keys) sa aj tak posielajú s každou požiadavkou v HTTP hlavičkách. A odhlásenie prebehne aj automaticky v prípade automatickej expirácie session do D2000 konfigurovateľnej v autentifikačnej časti konfigurácie SmartWeb Platformy. Niekedy je ale výhodné používať explicitné prihlásenie a odhlásenie v prípadoch keď toto API je využívané napr. z mobilnej aplikácie veľkým počtom používateľov.

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>

Napríklad pre nasledujúce HTTP GET volanie:

GET http://localhost/smartWeb/api/rest/v0/d2/archive/H.AdeunisRF1External<meno archívneho objektu>?beginTime=504501912000<celé číslo>&endTime=1504601912000

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

Blok kódu

language	js

[
	[
		1503492475090,
		23.2
	],
	[
		1503642560209,
		23.2
	],
	[
		1503643165774,
		23.3
	],
	...
]

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

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 adresu:

=<celé číslo>&oversampleSeconds=<celé číslo>&limitDataLength=<celé číslo>returnFields=<text>

Význam jednotlivých parametrov je nasledovný:

Meno parametra	Typ	Povinný	Popis
`beginTime`	celé číslo (počet milisekúnd od epochy)	áno	začiatok časového intervalu vyžiadaných hodnôt archívu
`endTime`	celé číslo (počet milisekúnd od epochy)	áno	koniec časového intervalu vyžiadaných hodnôt archívu
`oversampleSeconds`	celé číslo (počet sekúnd)	nie	dĺžka intervalu v sekundách pre oversampling dát, ak nie je definovaný vrátia sa originálne dáta
`limitDataLength`	celé číslo (počet hodnôt)	nie	maximálny počet vrátených hodnôt, ak nie je definovaný vrátia sa všetky hodnoty z intervalu
`returnFields`	text (definované Unival atribúty oddelené čiarkou )	nie	vyžiadané Unival atribúty, ktoré budú vrátené spolu s časovou známkou a hodnotou. Napr: `"Status,Flags"`

Napríklad pre nasledujúce HTTP GET volanie:

GET http://localhost/smartWeb/api/rest/v0/d2/archive/H.AdeunisRF1External?beginTime=504501912000&endTime=1504601912000

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

Blok kódu

language	js

[
	[
		1503492475090,
		23.2
	],
	[
		1503642560209,
		23.2
	],
	[
		1503643165774,
		23.3
	],
	...
]

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é.

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ý:

Meno parametra	Typ	Povinný	Popis
`beginTime`	celé číslo (počet milisekúnd od epochy)	áno	začiatok časového intervalu vyžiadaných hodnôt archívu
`endTime`	celé číslo (počet milisekúnd od epochy)	áno	koniec časového intervalu vyžiadaných hodnôt archívu
`period`	reťazec alebo číslo identifikujúci prevzorkovaciu periódu	nie	dĺžka intervalu v sekundách pre oversampling dát, ak nie je definovaný vrátia sa originálne dáta

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:

Blok kódu

language	js

{
	"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

Blok kódu

language	js
title	obsah POST requestu

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

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

Blok kódu

language	js

{
	"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 adresy:

POST https://<doména.sk>POST https://<doména.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/javajapi/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.SmartWeb_DemoE.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.

POST http://localhost/smartWeb/api/rest/v0/d2/rpc/E.E.SmartWeb_DemoSmartWebApiTutorial/TestInOut

Blok kódu

language	js
title	Príklad volania RPC metódy

[
  {
    "type": "bool",
    "value": "vTrue",
    "returnAs": "boolParam" // výstupná hodnota bude pod názvom boolParam
  },
  123,
  {
    "type": "real",
    "value": 10.9,
    "returnAs": "realParam", // výstupná hodnota bude pod názvom realParam
    "returnFields": ["ValueTime", "Status"] // k výstupnej hodnote sú požadované aj atribúty ValueTime a Status
  },
  {
    "type": "time",
    "returnAs": "timeParam" // výstupná hodnota bude pod názvom timeParam
  },
  "hello D2000"
]

...

Parametre dotazu (časť za otáznikom) sú automaticky preposlané do SBA metódy tak, ako boli zadané do adresy. Jediný preddefinovaný parameter je fileName, ktorý hovorí, ako sa bude sťahovaný súbor volať (kvoli downloadovaniu z prehliadača)Parameter fileName definuje meno sťahovaného súboru pod ktorým webový prehliadač uloží súbor na disk. Ak sa tento parameter nenastaví, tak názov downloadovaného súboru bude implicitne "file.dat". Okrem toho Smart Web server pridáva pre SBA RPC ešte parameter sessionUserName, kvoli identifikácii používateľa ktorý SBA RPC volá. Ostatné parametre závisia od konkrétnej implementácie volania SBA RPC metódy. SBA RPC metóda všetky zadané parametre dostane vo vstupnom poli bajtov (byte[]).

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.SmartWeb_DemoE.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.SmartWeb_DemoSmartWebApiTutorial/reportContract_PDF?fileName=report.pdf&id=10

...

Blok kódu

language	java

package app.runnables;

import app.wrappers.E$E.E$SmartWebSmartWebApiTutorial_Demo__$WRAPPER$__;

import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.HashMap;
import java.util.List;


public class E$SmartWeb_DemoE$E.SmartWebApiTutorial extends E$SmartWeb_DemoE$E.SmartWebApiTutorial__$WRAPPER$__ {

    public byte[] reportContract_PDF(byte[] urlParamsBytes) throws IOException {
		// naparsovanie poslaných URL paramatrov do hash-mapy
        final HashMap<String, String> parameters = getParametersFromUrlQueryString(urlParamsBytes);
		// Vyparsovanie parametra id do premennej
        final long contractId = Long.parseLong( long contractId = Long.parseLong(parameters.get("id"));
		// Získanie mena aktuálneho používateľa volajúceho SBA RPC
        final String userName = parameters.get("idsessionUserName"));
        System.out.println("DEBUG: Downloading contract with id " + contractId);
        // Vyrobenie cesty k súboru s daným reportom
        Path path = Paths.get("D:/D2000/Contract" + contractId + ".pdf");
		// Načítanie obsahu súboru a jeho vrátenie ako pole bajtov
        return Files.readAllBytes(path);
    }

	/**
	  * Utility metóda, vráti naparsované URL parametre z vstupného poľa byte[]
	  **/	
    private HashMap<String, String> getParametersFromUrlQueryString(byte[] urlQueryStringBytes) throws UnsupportedEncodingException {
        final String urlParamsString = new String(urlQueryStringBytes, "UTF-8");
        final List<String> paramPartsList = Arrays.asList(urlParamsString.split("&"));
        final HashMap<String, String> parameters = new HashMap<String, String>();
        for (String paramPartsString : paramPartsList) {
            final String[] paramParts = paramPartsString.split("=");
            final String paramName = paramParts[0];
            final String paramValue = paramParts.length > 1 ? paramParts[1] : null;
            parameters.put(paramName, paramValue);
        }
        return parameters;
    }
};

...

Posielanie binárnych dát do D2000 je možné cez HTTP POST metódu na identickú url linku pri sťahovaní binárnych dát, s tou istou HTTP hlavičkou Content-Type: application/octet-stream.

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

...

Ako alternatíva k predchádzajúcej možnosti kódovania vstupných parametrov spolu s obsahom na strane klienta je volanie SBA RPC metódy cez HTTP POST s inou hodnotou HTTP hlavičky: Content-Type: multipart/form-data. V tomto prípade sa v telo POST volania kóduje podľa definovaného štandardu na posielanie uploadovanie obsahu formulárov aj s binárnymi súbormi z prehliadača. Smart Web SmartWeb podporuje aj tento formát na volanie SBA RPC metód. Vstupný parameter pri volani SBA RPC metódy bude v tomto prípade obsahovať obsah jhodnôt ednotlivých hodnôt jednotlivých polí formulára zazipovaný spôsobom ako bol popísaný v predchádzajúcej kapitole. T.j. na rozkódovanie parametrov je možné využiť už uvedenú Java metódu loadParameters.

Info
Smart Web server v tomto prípade tak isto ako pri stiahnutí binárnych dát z D2000 cez HTTP GET, automatický pridáva pre SBA RPC aj parameter sessionUserName, kvoli identifikácii používateľa ktorý SBA RPC volá.

Strom stránky

Porovnávané verzie

Stará verzia 19

Nová verzia Aktuálny

Kľúč

Autentifikácia

Načítavanie hodnôt z archívu

Načítavanie hodnôt z archívu

Volanie D2000 RPC metód

Načítavanie hodnôt EDA vektora

Zápis hodnôt do EDA vektora

Volanie D2000 RPC metód

Strom stránky

História stránky

Porovnávané verzie

Stará verzia 19

Nová verzia Aktuálny

Kľúč

Autentifikácia

Načítavanie hodnôt z archívu

Načítavanie hodnôt z archívu

Volanie D2000 RPC metód

Načítavanie hodnôt EDA vektora

Zápis hodnôt do EDA vektora

Volanie D2000 RPC metód