Rest API » Historie » Revize 23
Revize 22 (Vojtěch Váchal, 2022-04-02 08:22) → Revize 23/28 (Vojtěch Váchal, 2022-04-09 14:23)
h1. 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
----
h3. Architektura
V DMS byl přidán soubor s architekturou -> {{dmsf(727)}}
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.
----
h3. Vstupní JSON
Pro implementaci bude využita nejspíše funkce Neurop3/Services/TestSerivce/saveResult:347
Vzhled dtoIn -> {{dmsf(725)}}
----
h3. 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
h4. Návrh JSONu
Co se týká JSON objektu, byla schválena následují podoba viz. příloha -> {{dmsf(724)}}
Pro vytvoření metod lze použít následující konfiguraci pro PostMan -> {{dmsf(723)}}
h4. 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í"_)
----
h3. 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
h4. 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"_
h4. 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"_
h4. 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
h4. Základní scénář
# Připojení pacienta k internetu.
# Po zapnutí aplikace request s datumem posledního stažení změn.
# 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.
# 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).
----
h3. 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
h4. -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ší--
h4. 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*
h4. -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í, ...-
h3. 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
h3. 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]])