The REST API rozhranie implementované 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 SmartWeb servera

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

interface implemented by the SmartWeb platform can be divided into the following parts: 

• interface for authentication
• interface for access to data and services of the D2000 system 
• administrative interface for monitoring calls into D2000 and a state of the SmartWeb server

These parts of the REST API interface are described in the following chapters.

Authentication

As we have already mentioned in the chapter Other Functions of the SmartWeb Platform, the supported way of authentication for the REST API is HTTP-BASIC. This type of authentication sends the user name and password directly in the header of every HTTP request. This means that every REST API request also automatically authenticates the user. In the case of an unsuccessful authentication, the server returns the status 404 in the header of the HTTP response. That is why it is not necessary to have an explicit login into the REST API interface via a special URL. Despite that, it is optimal to extract the function because of applications in which users login explicitly and thus the application needs to verify the given name and password.

Verifying of successful authentication is thus possible by sending an empty GET request with the HTTP-BASIC authentication to the addressOverenie ú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<domain.sk>/<názov aplikácie><application name>/api/rest/v0/d2/auth/login

Odhlásenie sa realizuje odoslaním prázdnej GET požiadavky s Logout is realized by sending an empty GET request with the HTTP-BASIC autentifikáciou na adresuauthentication to the address:

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

Načítavanie hodnôt z archívu

Reading Values from Archive

Reading values from an archive is possible via the GET request with the HTTP header Načítavanie hodnôt z archívu je možné cez GET požiadavku s HTTP hlavičkou Content-Type: application/json na adresu to the address:

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

Význam jednotlivých parametrov je nasledovný:

...

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

...

Meanings of individual parameters are as follows: 

For example, for the following HTTP GET callsNapríklad pre nasledujúce HTTP GET volanie:

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

we will get the response with an array of historical values from the server: dostaneme zo servera odpoveď s poľom archívnych hodnôt:

[
	[
		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

Every historical value is represented by an individual array due to the size of the transmitted message, and the first array element is always a time stamp and the second is always a value. In the case of defining other returning arrays by the parameter returnFields, these parameters are returned in other elements of an array according to the order in which they were defined.

Calling of D2000 RPC Methods

Via the REST interface, it is possible to call D2000 RPC procedures written in ESL and also in Java. Calling of ESL RPC procedures happens by sending a POST request with the HTTP header 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 to the address:

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

in the case of Java RPC calling is URL as follows:  v prípade volania Java RPC je URL nasledovná:

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

The body of the sent message is the JSON array with parameters of calling RPC. The output of such request are values of output RPC parameters stored in the JSON object, attributes of which are required names of output parameters defined by the attributes returnAs. Details of serialization of RPC method parameters were described in the previous chapter. The example of calling RPC with the name TestInOut on the eventTelo 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 with five parameters, while the first, the third and the fourth parameter is an input-output one and defines a logical name for returned parameters' values. Input parameters (the second and the fifth) also use implicit conversion on the Unival object from simple JSON types.

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

[
  {
    "type": "bool",
    "value": "vTrue",
    "returnAs": "boolParam" // the výstupnáoutput hodnotavalue budewill podbe názvomnamed boolParam
  },
  123,
  {
    "type": "real",
    "value": 10.9,
    "returnAs": "realParam", // the výstupnáoutput hodnotavalue budewill podbe názvomnamed realParam
    "returnFields": ["ValueTime", "Status"] // kattributes výstupnejValueTime hodnoteand súStatus požadovanéare ajrequired atribútyto ValueTimethe aoutput Statusvalue too
  },
  {
    "type": "time",
    "returnAs": "timeParam" // the výstupnáoutput hodnotavalue budewill podbe názvomnamed timeParam
  },
  "hello D2000"
]

Kód volanej RPC metódy môže byť napríklad:The code of the called RPC method can be for example:  

RPC PROCEDURE TestInOut(BOOL _bool, IN INT _int, REAL _real, TIME _time, IN TEXT _text)
  _bool := !_bool
  _real := _real / 2
  _time := SysTime
END TestInOut

Výstup z volania RPC je v JSON objekte, ktorý má atribúty podľa požadovaných názvov výstupných parametrovThe output of the RCP calling is in the JSON object which has attributes according to the required names of output parameters:

{
  "realParam": {
    "type": "real",
    "value": 5.45,
    "status": [
      "Valid"
    ],
    "valueTime": 1498213794522
  },
  "boolParam": {
    "type": "bool",
    "value": "vFalse"
  },
  "timeParam": {
    "type": "time",
    "value": 1498213794012
  }
}

...

Calling of D2000 SBA RPC

...

Methods

Pretože D2000 nepozná binárny dátový typ, RPC procedúry nie sú na presun binárnych dát vhodné. Na tento účel slúžia Because D2000 does not know binary data type, RPC procedures are not suitable for binary data transfer. The Simple Byte Array (SBA) metódy napísané v D2000 Javemethods written in the D2000 Java serve for this purpose.

...

Downloading of Binary Data from D2000 via HTTP GET (URL

...

Link)

Na stiahnutie binárnych dát z D2000 na klienta slúži GET príkaz s HTTP hlavičkou To download binary data from D2000 to a client, we use the GET command with the HTTP header Content-Type: application/octet-stream na adresestream on the address: 

GET https://<doména<domain.sk>/<názov aplikácie><application name>/api/rest/v0/d2/sba/<meno eventu>/<meno SBA RPC metódy><event name>/<SBA RPC method name>?fileName=file.dat[&parameterX=hodnotaXvalueX&parameterY=hodnotaYvalueY&...]

Parametre dotazu (časť za otáznikom) sú automaticky preposlané do SBA metódy tak, ako boli zadané do adresy. 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 Parameters of the query (the part after the question mark) are automatically sent to the SBA method in the same way as they were inputted into the address. The parameter fileName defines the name of the downloaded file under which the web browser will store the file on the disc. If this parameter is not set, the name of the downloaded file will be implicitly "file.dat". Okrem toho Besides that, the Smart Web server pridáva pre adds for SBA RPC ešte also the parameter sessionUserName , kvoli identifikácii používateľa ktorý for identification of a user who calls 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 . Other parameters depend on the particular implementation of SBA RPC method calling. The SBA RPC method gets all the inputted parameters in the input byte array (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.E.SmartWebApiTutorial s parametrom id ktorý identifikuje číslo reportu a tým pádom sťahovaného súboruThe following example illustrates the calling and implementation of the SBA RPC method for downloading a particular file of the pdf report from the local file system. The following example, however, is not suitable at all for a real usage and it is only for illustration of SBA RPC calling. Calling of SBA RPC method reportContract_PDF in the event E.E.SmartWebApiTutorial with the parameter id which identifies the report number and thus the downloaded file.

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

Implementácia The implementation of the SBA RPC metódy je nasledovná:method is as follows: 

package app.runnables;

import app.wrappers.E$E.SmartWebApiTutorial__$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$E.SmartWebApiTutorial extends E$E.SmartWebApiTutorial__$WRAPPER$__ {

    public byte[] reportContract_PDF(byte[] urlParamsBytes) throws IOException {
		// Parsing naparsovanieof poslanýchsent URL paramatrovparamaters dointo hash-mapymap
        final HashMap<String, String> parameters = getParametersFromUrlQueryString(urlParamsBytes);
		// VyparsovanieParsing parametraparameters id dointo premennejvariable
        final long contractId = Long.parseLong(parameters.get("id"));
		// Acquiring the Získaniename menaof aktuálnehocurrent používateľauser volajúcehocalling SBA RPC
        final String userName = parameters.get("sessionUserName");
        System.out.println("DEBUG: Downloading contract with id " + contractId);
        // Vyrobenie cesty k súboru s daným reportom Creating a path to the file with the given report
        Path path = Paths.get("D:/D2000/Contract" + contractId + ".pdf");
		// Načítaniereading obsahufile content súboruand aits jehoreturn vrátenieas akoa polebyte bajtovarray
        return Files.readAllBytes(path);
    }

	/**
	  * Utility metódamethod, it vrátireturns naparsovanéparsed URL parameters parametrefrom zthe vstupnéhoinput poľaarray 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;
    }
};

...

Sending Binary Data to D2000 via HTTP POST

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 Sending binary data to D2000 is possible via HTTP POST method to an identical URL link when downloading binary data with the same HTTP header Content-Type: application/octet-stream.  

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

Pri posielaní binárnych dát nie je možné poslať špecifické URL parametre priamo do SBA RPC metódy.  Hodnota vstupného parametra SBA RPC metódy bude v tomto prípade binárny obsah posielaný v tele POST requestu. Klient ale nie je žiadnym spôsobom obmedzený typom obsahu, ktorý posiela cez HTTP POST request. Jediná požiadavkou je, aby binárny obsah vedela rozkódovať príslušná implementácia SBA RPC metódy, analogicky ako v predchádzajúcom prípade keď sme ilustrovali rozkódovanie URL parametrov špeciálnou utility metódou  getParametersFromUrlQueryString(). Ak klient potrebuje posielať s binárnym obsahom aj dodatočné vstupné parametre (napr. identifikujúce tento obsah), je zakódovanie a rozkódovanie takéhoto obsahu v SBA RPC plne v jeho kompetencii. Nasledujúca kapitola obsahuje odporúčaný spôsob takéhoto kódovania.

Odporúčaný spôsob kódovania vstupných parametrov spolu s binárnym obsahom

V prípade že so samotným binárnym obsahom potrebujeme v rámci volania SBA RPC metódy posielať aj ďalšie vstupné parametre, odporúčame kódovať parametre ako aj priložený obsah do zip streamu. Výhodou takéhoto riešenia je univerzálnosť a jednoduchosť použitia vo väčšine programovacích jazykov (ZIP kompresia býva väčšinou dobre podporená buď v štandardnej knižnici daného jazyka alebo v nejakej inej voľne dostupnej verzii knižnice).

<event name>/<SBA RPC method name>

When sending binary data, it is not possible to send specific URL parameters directly to the SBA RPC method. The value of the input parameters of the SBA RPC method will be in this case a binary content sent in the body of the POST request. However, clients are in no way limited by the content type which they send via the HTTP POST request. The only condition is for the binary content to be able to decode the relevant implementation of the SBA RPC method, analogically as in the previous case when we illustrated decoding of URL parameters with a special utility by the method getParametersFromUrlQueryString(). If the client needs to send with the binary content also additional input parameters (e.g. identifying the content), encoding and decoding of such content in SBA RPC will be completely in his competency. The following chapter contains the recommended way of such coding. 

Recommended way of coding input parameters together with binary content 

In the case that we need to send with the binary content itself also other input parameters within calling of the SBA RPC method, we recommend encoding parameters also with the attached content into a zip stream. The advantage of such solution is the universality and simplicity of usage in most of the programming languages (ZIP compression is mostly well-supported either in the standard library of the given language or in some other freely available version of a library).

We show an example of compression of more parameters into one ZIP byte stream in Java on the client's sideUvádzame príklad kompresie viacerých parametrov do jedného ZIP byte streamu v Jave na strane klienta:

/**
  * Proposal method how to serialize multiple key-value pairs to byte array
  */
  @SuppressWarnings("unused")
  private byte[] writeParameters(Map<String, byte[]> params) throws IOException {
      try (ByteArrayOutputStream baos = new ByteArrayOutputStream()) {
          try (ZipOutputStream zos = new ZipOutputStream(baos)) {
              for (Map.Entry<String, byte[]> entry : params.entrySet()) {
                  final ZipEntry zipEntry = new ZipEntry(entry.getKey());
                  zipEntry.setSize(entry.getValue().length);
                  zos.putNextEntry(zipEntry);
                  zos.write(entry.getValue());
                  zos.closeEntry();
              }
          }
          return baos.toByteArray();
      }
 }

Príklad rozkódovania ZIP byte streamu na strane SBA RPC potom budeThen an example of decoding the ZIP byte stream on the SBA RPC side will be:

/**
  * Proposal method how to deserialize multiple key-value pairs from byte array
  */
@SuppressWarnings("unused")
private Map<String, byte[]> loadParameters(byte[] inputBytes) throws IOException {
    final Map<String, byte[]> dataParts = new HashMap<String, byte[]>();
    try (ByteArrayInputStream byteArrayInputStream = new ByteArrayInputStream(inputBytes)) {
        try (ZipInputStream zipInputStream = new ZipInputStream(new ByteArrayInputStream(inputBytes))) {
            ZipEntry zipEntry = zipInputStream.getNextEntry();
            byte[] buffer = new byte[4096];
            while (zipEntry != null) {
                final ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
                int len;
                while ((len = zipInputStream.read(buffer)) > 0) {
                    outputStream.write(buffer, 0, len);
                }
                final byte[] data = outputStream.toByteArray();
                dataParts.put(zipEntry.getName(), data);
                zipEntry = zipInputStream.getNextEntry();
            }
        }
    }
    return dataParts;
}

Automatické kódovanie vstupných parametrov spolu s binárnym obsahom

Automatic coding of input parameters together with binary content 

As an alternative to a previous way of coding input parameters together with the binary content on the client's side is calling SBA RPC method via HTTP POST with another value of the HTTP header 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. 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 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 In this case, the body of the POST calling is coded according to the defined standard for sending forms also with binary files from a browser. SmartWeb supports also this format for calling SBA RPC methods. The input parameter when calling the SBA RPC method will contain in this case content of values of individual form arrays zipped in a way described in the previous chapter. This means that for decoding parameters, it is possible to use already mentioned Java method loadParameters.