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>
...
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é.
...
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 | ||||
---|---|---|---|---|
| ||||
[ { "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" ] |
...
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.SmartWeb_DemoSmartWebApiTutorial
s parametrom id
ktorý identifikuje číslo reportu a tým pádom sťahovaného súboru.
GET
http://localhost/smartWeb/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$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(parameters.get("id")); 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 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 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
.
...