Rest API¶

• offline mobilní aplikace
• při připojení k internetu bude posílat dosažené výsledky a stahovat nové úlohy a balíky přidělené terapeutem
• potřeba navrhnout a implementovat Rest API, se kterým bude moct aplikace komunikovat

---

Architektura¶

V DMS byl přidán soubor s architekturou ->

Jedná se o návrh architektury. Spíš o jednotlivé částí aplikace, kde se vývoj požadavku bude odehrávat.
Co se týká změn, ty budou pouze aditivní. Nebudou se zde odehrávat žádné změny stávající funkcionality.

---

Vstupní JSON¶

Pro implementaci bude využita nejspíše funkce Neurop3/Services/TestSerivce/saveResult:347
Vzhled dtoIn ->

---

App version - .NET Framework 3.6.1.

---

Schůzka s M. Horkým dne 22. března 2022¶

• záznam ze schůzky, kde se řešil návrh JSON objektu, který bude odesílán z webové aplikace a diskuze nad ověřováním uživatele

Návrh JSONu¶

Co se týká JSON objektu, byla schválena následují podoba viz. příloha ->

Pro vytvoření metod lze použít následující konfiguraci pro PostMan ->

Ověřování uživatele¶

• v aktuální implementaci se využívá nějaká .NET knihovna, která hashování řeší sama
• nakonec bylo domluveno, že mobilní aplikace bude posílat jméno a heslo v plaintext formě
  • přes SSL
• v budoucnu lze přistoupit k asymetrickému šifrování či změnit implementaci ověřování ("udělat si vlastní")

---

Schůzka s M. Horkým dne 14. března 2022¶

• záznam ze schůzky, kde se probíral návrh API a dořešení dalších otázek, které vznikly při analýze

Odesílání souborů¶

• odesílat se budou komprimované soubory pomocí kompresního programu Gzip
• následně se bude soubor převádět do řetězce v Base64 formátu, který bude přiložen do odesílaného JSONu
• dle zákazníka se zatím jedná pouze o prvotní verzi a není prý úplně důvod tolik řešit optimalizaci
  • "z počátku (v prvních iteracích) upřednostnit jednodušší a rychlejší řešení, než optimalizaci - tu pak můžeme dotáhnout, když to půjde hladce a zbyde čas"

Autorizace¶

• co se týká autorizace, řešení je zcela na nás
• nejspíše nebude potřeba speciální endpoint pro ověřování
• potřeba zaheshovat login a heslo
  • "ověření pacienta (hashovaný login/heslo) - potřebuji pak informaci o typu hashovací funkce"

Endpointy a data¶

• celkový počet endpointů zatím vypadá na 2
  • asi nebudeme vytvářet Swagger API, nemá moc smysl pro 2 endpointy
• formát komunikace JSON
• návrh API proběhne v iterace od 15.3. - 29.3.2022

Základní scénář¶

1. Připojení pacienta k internetu.
2. Po zapnutí aplikace request s datumem posledního stažení změn.
3. Zpět informace o nových změnách (nově přidělené balíky, změny v přidělených úlohách).
   • U každé úlohy potřebuji ID šablony.
   • Ke každé úloze by také měla být kompletní konfigurace včetně všech multimediálních souborů.
   • Datum změny by mohlo být umístěno někde v databázi - prověřit.
4. Kdykoli se pak může odeslat JSON s nasbíranými daty.
   • Tady pozor na možné změny v balících - pokud nedošlo k celkovému odstranění úlohy - myslím opravdu celkovému ne pouze z balíku - tak by se data měla uložit vždy).

---

Odesílání souborů přes Rest API¶

• po analýze bylo zjištěno a nalezena 2 řešení, která by byla možná implementovat
• potřeba probrat s M. Horkým na nějaké schůzce, které řešení se zvolí, zda by bylo potřeba řešit úplně jinak

1. Řetězec v Base64¶

• Base64 je kódování, které převádí binární data na posloupnosti tisknutelných znaků.
• umožňuje přenos binárních dat kanály, které dovolují pouze přenos textů.
• Výhody:
  • funguje na jakákoliv binární data (obrázky, soubory, ...)
  • velice jednoduchá implementace v C#
• Nevýhody
  • největší nevýhodou tohoto řešení je, že velikost vytvořeného/odesílaného řetězce je zhruba o 20-30% větší-

2. Komprimované Base64¶

• nevýhodu prvního řešení lze odstranit nějakou kompresí (Gzip, DeflateStream, ...)
• podle zvolené komprese by se sice ztrácela kvalita obrázků, ale přenos dat by se mohl zrychlit, protože velikost dat by měla být menší
  • nechceme aby stahování/odesílání trvalo příliš dlouho (pacient může trénovat pouze po dobu jedné hry, či pouze zkoumat dosažené výsledky)
• řešení by fungovalo tak, že by se
  • zapnula aplikace a zahájilo se tak stahování/odesílání potřebného obsahu
  • mobilní aplikace by přijala komprimovaný obrázek v base 64 formátu

• pokud by byla potřeba stejná kvalita obrázků, jak v aplikace tak v systému byla by možnost spolu s komprimovaným obrázkem posílat i url
  • url by obsahovala adresu, kde by se nacházel soubor v plné kvalitě
  • po stažení všech potřebných/nových dat ze systému by se na pozadí aplikace zahájilo stahování obrázků v plné kvalitě a nenarušovalo uživatele

3. Použít multipart/from-data namísto JSONu¶

• POST a PUT metody jsou RESTFull, jak jen to jde
  • obsahují textový vstup společně se soubory
• nevýhodou je, že přenos už nebude realizovaný pomocí JSONu, který je daleko jednodušší k testování, ladění, ...

Autorizace přeš API¶

• vhodné přes autorizační token získaný při přihlášení s omezenou platností
  • potřeba ujasnit u zákazníka (na předchozí schůzce zmiňoval, že ještě upřesní své požadavky)

• tento bod byl dne 14.3. vyjasněn se společníkem zákazníka (M. Horký)
  • konkrétní informace lze dohledat v tomto dokumentu výše (viz. #Schůzka s M. Horkým dne 14. března 2022)

• provedena analýza provedené hashovací funkce (viz https://stackoverflow.com/questions/20621950/asp-net-identitys-default-password-hasher-how-does-it-work-and-is-it-secure)
  • nutná konzultace se zákazníkem o vyhovujcí variantě authorizace
  • původní varianta ukládání zaheshovaného hesla by byla složita z důvodu solení hashe

Navrhované endpointy¶

• podoba endpointů bude vytvořena po zhodnocení nároků a vlastností mobilní aplikace pro kterou API vzniká

• tento bod byl dne 14.3. konzultován se společníkem zákazníka (M. Horký)
  • konkrétní informace lze dohledat v tomto dokumentu výše (viz. #Schůzka s M. Horkým dne 14. března 2022)