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.
...
Ako už bolo spomenuté v kapitole Ďalšie funkcie Smart Web SmartWeb platformy, podporovaný spôsob autentifikácie pre REST API je HTTP-BASIC. Tento typ autentifikácie 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é meno a heslo.
...
Info |
---|
Volanie explicitného odhlásenie je odporúčané z dôvodov že Smart Web SmartWeb 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 SmartWeb 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 https://<doména<doména.sk>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ý:
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:
...
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 adresujednu z adries:
POST https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/rpc/<meno eventu>/<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/javainterface/<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>/<názov aplikácie>/api/rest/v0/d2/rpc/japi/<meno procesu>/<meno RPC metódy>
POST https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/rpc/japi/interface/<meno procesu>/<meno interfacu>/<meno RPC metódy>
Telo odosielanej správy je JSON pole s parametrami volanej RPC. Výstupom takejto požiadavky sú 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.SmartWeb_DemoSmartWebApiTutorial
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.SmartWeb_DemoE.SmartWebApiTutorial/TestInOut
Blok kódu | ||||
---|---|---|---|---|
| ||||
[ { "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.SmartWeb_DemoE.SmartWebApiTutorial/reportContract_PDF?fileName=report.pdf&id=10
...
Blok kódu | ||
---|---|---|
| ||
package app.runnables; import app.wrappers.E$E.E$SmartWeb_DemoSmartWebApiTutorial__$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(.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á. |