Rest API » Historie » Revize 18
Revize 17 (Vojtěch Váchal, 2022-03-23 13:53) → Revize 18/28 (Vojtěch Váchal, 2022-03-26 15:28)
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. 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 -> attachment:json_desing_out.txt Pro vytvoření metod lze použít následující konfiguraci pro PostMan - attachment:BrainIn_Rest_API.postman_collection.json 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]])