Rest API » Historie » Verze 28
Vojtěch Váchal, 2022-05-11 07:38
1 | 1 | Vojtěch Váchal | h1. Rest API |
---|---|---|---|
2 | |||
3 | * offline mobilní aplikace |
||
4 | * při připojení k internetu bude posílat dosažené výsledky a stahovat nové úlohy a balíky přidělené terapeutem |
||
5 | * potřeba navrhnout a implementovat Rest API, se kterým bude moct aplikace komunikovat |
||
6 | |||
7 | ---- |
||
8 | |||
9 | 28 | Vojtěch Váchal | h3. Průběžné informace |
10 | |||
11 | Všechny problémy byly prozatím odstraněny. Aktuální verze API je nasazena na vývojovém prostředí. Při vytváření dokumentace byly odhaleny některé chyby, které je potřeba tento týden odstranit. |
||
12 | |||
13 | Zároveň byla domluvena schůzka s M. Horkým ohledně představení práce s rozhraním a nasdílení všech materiálů, které budou potřeba pro následné externí testování. |
||
14 | |||
15 | Zároveň byly k datu 11.5. aktualizovány všechny potřebné soubory v DMS. |
||
16 | |||
17 | ---- |
||
18 | |||
19 | 26 | Vojtěch Váchal | h3. Další problémy s binárními soubory |
20 | |||
21 | Po přípravě prototypu a začátku testování bylo zjištěno, že výstupní funkce generuje moc velké objekty pro jednu úlohu (cca 400 obrázků -> 80MB, s kompresí 70MB). |
||
22 | Po krátké diskuzi se zadavatelem bylo zjištěno, že tento výsledek je nechtěný, prostě to je moc dat, které by se posílaly, kdy by se jednalo o více úloh najednout. |
||
23 | |||
24 | |||
25 | h4. Nové řešení odesílání binárních souborů |
||
26 | |||
27 | Na základě konverzace je potřeba upravit odesílání binárních souborů následovně. |
||
28 | Bude potřeba, posílat nějaké informace ke každému obrázku. Porovnání bude probíhat v mobilní aplikaci a případné originální obrázky se stáhnu přes endpoint. Místo cesty k obrázku bude objekt, který bude obsahovat následující informace (lze to vyřešit i přes index do pole s informacemi o obrázcích - to už je jedno): cestu k souboru, paměťovou velikost, šířku, výšku a ideálně průměrné hodnoty RGB kanálů a jasu (zaokrouhlené na celá čísla - je jedno jestli dolů nebo nahoru, vyhnul bych se ale klasickému zaokrouhlování). Hodnoty RGB + jas pro každý pixel lze najít v instancích třídy Color. Ty atributy ve webové aplikaci budou nejspíše pojmenovány R, G, B, A a grayscale lze získat přes funkci GetBrightness(). |
||
29 | |||
30 | U zvuku bychom mohli řešit dobu trvání, přenosovou rychlost, velikost a případně další. |
||
31 | |||
32 | K těm dalším typům binárních souborů - musíme počítat třeba s GIFy. Mohli bychom to prozatím pořešit tak, že když to nebude obrázek a zvuk, tak budeme porovnávat pouze název a paměťovou velikost. |
||
33 | 27 | Vojtěch Váchal | |
34 | 26 | Vojtěch Váchal | ---- |
35 | |||
36 | 25 | Vojtěch Váchal | h3. Schůzka s M. Horkým dne 11. dubna 2022 |
37 | |||
38 | h4. Binární soubory |
||
39 | |||
40 | V úlohách se vyskytují binární soubory. Problém nastává u endpointu, který přijímá výsledky z mobilní aplikace. Na vstupu má totiž řetězec, ve kterém by se vyskytoval "někde" base64 řetězec, který reprezentuje obrázek. |
||
41 | |||
42 | Na schůzce bylo domluveno, že se použije již vytvořený endpoint pro ukládání souborů (nutno najít). Mobilní aplikace nejdříve uloží všechny obrázky pomocí této funkce a následně cesty k souborům pošle standardně ve stringu (jak tomu již je ve webových verzích hrách). |
||
43 | |||
44 | h4. Lokalizace |
||
45 | |||
46 | Na schůzce se řešilo, jakým způsobem se budou posílat do mobilní aplikace lokalizace textů a parametrů úlohy. |
||
47 | Návrhem a schváleným řešením se nakonec stalo to, že spolu s přihlaš. údaji bude mobilní aplikace posílat i informaci, ve které lokalizaci se budou úlohy odesílat. |
||
48 | |||
49 | Zároveň je ještě potřeba udělat analýza na to, zdali je velký rozdíl ve velikost odesílaných dat při odesílání konkrétní nebo všech lokalizací. Hlavně otestovat na logopedických úlohách (na produkci). |
||
50 | |||
51 | + bylo by nejlepší vytvořit sdílené prostředí pro nás a M. Horkého, aby viděl aktuální verze návrhů atd. |
||
52 | |||
53 | ---- |
||
54 | |||
55 | 23 | Vojtěch Váchal | h3. Architektura |
56 | |||
57 | V DMS byl přidán soubor s architekturou -> {{dmsf(727)}} |
||
58 | |||
59 | Jedná se o návrh architektury. Spíš o jednotlivé částí aplikace, kde se vývoj požadavku bude odehrávat. |
||
60 | Co se týká změn, ty budou pouze aditivní. Nebudou se zde odehrávat žádné změny stávající funkcionality. |
||
61 | |||
62 | ---- |
||
63 | |||
64 | 20 | Vojtěch Váchal | h3. Vstupní JSON |
65 | |||
66 | Pro implementaci bude využita nejspíše funkce Neurop3/Services/TestSerivce/saveResult:347 |
||
67 | 22 | Vojtěch Váchal | Vzhled dtoIn -> {{dmsf(725)}} |
68 | 21 | Vojtěch Váchal | |
69 | ---- |
||
70 | 20 | Vojtěch Váchal | |
71 | 24 | Jan Bartošek | App version - .NET Framework 3.6.1. |
72 | |||
73 | ---- |
||
74 | |||
75 | 20 | Vojtěch Váchal | h3. Schůzka s M. Horkým dne 22. března 2022 |
76 | |||
77 | 13 | Vojtěch Váchal | * 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 |
78 | |||
79 | h4. Návrh JSONu |
||
80 | |||
81 | 22 | Vojtěch Váchal | Co se týká JSON objektu, byla schválena následují podoba viz. příloha -> {{dmsf(724)}} |
82 | 13 | Vojtěch Váchal | |
83 | 22 | Vojtěch Váchal | Pro vytvoření metod lze použít následující konfiguraci pro PostMan -> {{dmsf(723)}} |
84 | 13 | Vojtěch Váchal | |
85 | h4. Ověřování uživatele |
||
86 | |||
87 | * v aktuální implementaci se využívá nějaká .NET knihovna, která hashování řeší sama |
||
88 | * nakonec bylo domluveno, že mobilní aplikace bude posílat *jméno a heslo v _plaintext_ formě* |
||
89 | ** přes SSL |
||
90 | * v budoucnu lze přistoupit k asymetrickému šifrování či změnit implementaci ověřování (_"udělat si vlastní"_) |
||
91 | |||
92 | ---- |
||
93 | |||
94 | 9 | Vojtěch Váchal | h3. Schůzka s M. Horkým dne 14. března 2022 |
95 | 7 | Vojtěch Váchal | |
96 | * 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 |
||
97 | |||
98 | h4. Odesílání souborů |
||
99 | |||
100 | * odesílat se budou komprimované soubory pomocí kompresního programu *Gzip* |
||
101 | * 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 |
||
102 | * dle zákazníka se zatím jedná pouze o prvotní verzi a není prý úplně důvod tolik řešit optimalizaci |
||
103 | ** _"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"_ |
||
104 | |||
105 | h4. Autorizace |
||
106 | |||
107 | * co se týká autorizace, řešení je zcela na nás |
||
108 | * nejspíše nebude potřeba speciální endpoint pro ověřování |
||
109 | * potřeba zaheshovat login a heslo |
||
110 | ** _"ověření pacienta (hashovaný login/heslo) - potřebuji pak informaci o typu hashovací funkce"_ |
||
111 | |||
112 | h4. Endpointy a data |
||
113 | |||
114 | * celkový počet endpointů zatím vypadá na 2 |
||
115 | 8 | Vojtěch Váchal | ** asi nebudeme vytvářet Swagger API, nemá moc smysl pro 2 endpointy |
116 | 7 | Vojtěch Váchal | * formát komunikace *JSON* |
117 | * návrh API proběhne v iterace od 15.3. - 29.3.2022 |
||
118 | |||
119 | h4. Základní scénář |
||
120 | |||
121 | # Připojení pacienta k internetu. |
||
122 | # Po zapnutí aplikace request s datumem posledního stažení změn. |
||
123 | # Zpět informace o nových změnách (nově přidělené balíky, změny v přidělených úlohách). |
||
124 | ** U každé úlohy potřebuji ID šablony. |
||
125 | ** Ke každé úloze by také měla být kompletní konfigurace včetně všech multimediálních souborů. |
||
126 | ** Datum změny by mohlo být umístěno někde v databázi - prověřit. |
||
127 | # Kdykoli se pak může odeslat JSON s nasbíranými daty. |
||
128 | ** 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). |
||
129 | |||
130 | ---- |
||
131 | |||
132 | 1 | Vojtěch Váchal | h3. Odesílání souborů přes Rest API |
133 | |||
134 | * po analýze bylo zjištěno a nalezena 2 řešení, která by byla možná implementovat |
||
135 | * 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 |
||
136 | |||
137 | 7 | Vojtěch Váchal | h4. -1. Řetězec v Base64- |
138 | 1 | Vojtěch Váchal | |
139 | 7 | Vojtěch Váchal | * -Base64 je kódování, které převádí binární data na posloupnosti tisknutelných znaků.- |
140 | * -umožňuje přenos binárních dat kanály, které dovolují pouze přenos textů.- |
||
141 | * -Výhody:- |
||
142 | ** -funguje na jakákoliv binární data (obrázky, soubory, ...)- |
||
143 | ** -velice jednoduchá implementace v C#- |
||
144 | * -Nevýhody- |
||
145 | ** -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ší-- |
||
146 | 1 | Vojtěch Váchal | |
147 | h4. 2. Komprimované Base64 |
||
148 | |||
149 | 7 | Vojtěch Váchal | * *nevýhodu prvního řešení lze odstranit nějakou kompresí (Gzip, DeflateStream, ...)* |
150 | * *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ší* |
||
151 | ** *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)* |
||
152 | * *řešení by fungovalo tak, že by se* |
||
153 | ** *zapnula aplikace a zahájilo se tak stahování/odesílání potřebného obsahu* |
||
154 | ** *mobilní aplikace by přijala komprimovaný obrázek v base 64 formátu* |
||
155 | 1 | Vojtěch Váchal | |
156 | 7 | Vojtěch Váchal | * *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* |
157 | ** *url by obsahovala adresu, kde by se nacházel soubor v plné kvalitě* |
||
158 | ** *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* |
||
159 | 2 | Vojtěch Váchal | |
160 | 7 | Vojtěch Váchal | h4. -3. Použít multipart/from-data namísto JSONu- |
161 | 4 | Daniel Wébr | |
162 | 7 | Vojtěch Váchal | * -POST a PUT metody jsou RESTFull, jak jen to jde- |
163 | ** -obsahují textový vstup společně se soubory- |
||
164 | * -nevýhodou je, že přenos už nebude realizovaný pomocí JSONu, který je daleko jednodušší k testování, ladění, ...- |
||
165 | 4 | Daniel Wébr | |
166 | h3. Autorizace přeš API |
||
167 | |||
168 | 7 | Vojtěch Váchal | * -vhodné přes autorizační token získaný při přihlášení s omezenou platností- |
169 | ** -potřeba ujasnit u zákazníka (na předchozí schůzce zmiňoval, že ještě upřesní své požadavky)- |
||
170 | 1 | Vojtěch Váchal | |
171 | 7 | Vojtěch Váchal | * tento bod byl dne 14.3. vyjasněn se společníkem zákazníka (M. Horký) |
172 | 10 | Vojtěch Váchal | ** konkrétní informace lze dohledat v tomto dokumentu výše (viz. [[#Schůzka s M. Horkým dne 14. března 2022]]) |
173 | 7 | Vojtěch Váchal | |
174 | 12 | Daniel Wébr | * 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) |
175 | 11 | Daniel Wébr | ** nutná konzultace se zákazníkem o vyhovujcí variantě authorizace |
176 | ** původní varianta ukládání zaheshovaného hesla by byla složita z důvodu solení hashe |
||
177 | |||
178 | 1 | Vojtěch Váchal | h3. Navrhované endpointy |
179 | |||
180 | * podoba endpointů bude vytvořena po zhodnocení nároků a vlastností mobilní aplikace pro kterou API vzniká |
||
181 | 7 | Vojtěch Váchal | |
182 | 8 | Vojtěch Váchal | * tento bod byl dne 14.3. konzultován se společníkem zákazníka (M. Horký) |
183 | 9 | Vojtěch Váchal | ** konkrétní informace lze dohledat v tomto dokumentu výše (viz. [[#Schůzka s M. Horkým dne 14. března 2022]]) |