REST API rozhranie implementované Smart Web 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 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 Smart Web 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.

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

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:

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

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:

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

 v prípade volania Java RPC je URL nasledovná:

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

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_Demo 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_Demo/TestInOut

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

Kód volanej RPC metódy môže byť napríklad:

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

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

Volanie D2000 SBA RPC metód

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 Simple Byte Array (SBA) metódy napísané v D2000 Jave.

Stiahnutie binárnych dát z D2000 cez HTTP GET (URL linku)

Na stiahnutie binárnych dát z D2000 na klienta slúži GET príkaz na adrese: 

https://<doména.sk>/<názov aplikácie>/api/rest/v0/d2/sba/<meno eventu>/<meno SBA RPC metódy>?fileName=file.dat[&parameterX=hodnotaX&parameterY=hodnotaY&...]

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). Ak sa tento parameter nenastaví, tak názov downloadovaného súboru bude implicitne "file.dat". Ostatné parametre závisia od konkrétnej implementácie 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_Demo 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_Demo/reportContract_PDF?fileName=report.pdf&id=10

Implementácia SBA RPC metódy je nasledovná:

package app.runnables;

import app.wrappers.E$SmartWeb_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_Demo extends E$SmartWeb_Demo__$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 cez HTTP POST