Mapy.cz
Nástroje pro vývojáře
Chybějící dokumentace
Jan Janoušek
26.10.2021 v 19:46
1) user_id u https://login.szn.cz/api/v1/oauth/token je jakého typu? Bude to to 32 bitové, nebo 64 bitové číslo?
2) account_name u https://login.szn.cz/api/v1/oauth/token je vždy email? Může se stát, že bude obsahovat něco co není emailem? Pokud je vždy emailem, tak je email vždy ověřený?
3) JSON s odpovědí obsahuje například vlastnost "status". Jakých může nabývat hodnot? Není redundantní? Stejnou funkci by měl mít HTTP stavový kód, nebo ne?
A na závěr bych se ještě zeptal proč není ID uživatele, email, atd.. vracen i v rámci endpointu https://login.szn.cz/api/v1/user ?
Václav Pekárek
29.10.2021 v 7:55
také bych rád dodal, že by bylo vhodné dokumentaci rozšířit o schema objektů, které se z jednotlivých endpointů vrací.
Ondřej Žára
1.11.2021 v 15:14
principialne dava smysl z odpovedi cist pouze ty polozky, ktere jsou bud standardizovane (metoda "/token"), nebo dokumentovane. Proto jsme dnes dokumentaci rozsirili a zejmena popsali ruzne varianty dat odpovedi z metody "/user". Polozka "user_id" patri mezi ty nedokumentovane (a take jsme ji v nekterych pripadech prestali posilat).
Hodnota "account_name" je e-mailova adresa a je vzdy overena. Vyhledove to neni mozne slibit ani zarucit, protoze do budoucnosti nevidime. Pokud by mel tento invariant padnout, budeme o tom s predstihem informovat.
Pole "status" neni redundantni, nebot v rade pripadu se neshoduje s HTTP statusem. Spada vsak do magicke mnoziny nedokumentovanych hodnot, proto nezasluhuje blizsi upresneni.
V ramci endpointu "/user" je e-mailova adresa samozrejme take k dispozici, byt v odlisnem tvaru - konkretnejsi dokumentace k teto metode je pocinaje dneskem take k mani.
Tomas Hauso
2.11.2021 v 11:05
posledni zname datum kdy user_id bylo soucasti odpovedi je 27.10.2021
bylo by fajn takove zmeny delat v nove verzi aby puvodni api requesty fungovali
Jan Janoušek reagoval na příspěvek od Ondřej Žára
2.11.2021 v 20:01
když vezmu v úvahu to co jste mi napsal v reakci a aktuální dokumentaci tak tam máte docela zásadní problém. Odstranili jste "user_id" a zároveň jste napsal, že "account_name" nemusí být do budoucna ověřený. Otázka (řečnická) tedy je co je jednoznačný identifikátor toho účtu? Jak můžu poznat, že uživatel, který se teď přihlásil je "Pepa" a spárovat ho s "Pepou" v našem systému? Doteď jsem měl za to, že ten identifikátor je právě "user_id". To jste odstranili a "account_name" není zaručen. Nemluvě o tom, že pokud to již nyní někdo takto implementoval a nasadil tak jste mu tu implementaci právě rozbili.
Pokud můžu, tak bych navrhoval přidat nějakou vlastnost "is_verified", která by udávala jestli je email ověřen (i kdyby měla aktuálně vždy vracet true). Takto to má aktuálně například Google.
Každopádně to neřeší otázku co je nyní tím "identifikátorem" uživatele.
Ondřej Žára reagoval na příspěvek od Tomas Hauso
3.11.2021 v 10:28
pole "user_id" nebylo nikdy dokumentovano, ani oficialne verejne nabizeno. Jeho publikace byl omyl, ktery jsme opravili. Dokumentace explicitne zminovala, ze odpoved /token obsahuje e-mailovou adresu (coz je ten identifikator, ktery je pro treti stranu zajimavy).
Ondřej Žára reagoval na příspěvek od Jan Janoušek
3.11.2021 v 10:32
dokumentace od pocatku zminuje vyhradne e-mailovou adresu, ktera je zamyslena jako unikatni identifikator. V budoucnu v teto veci mohou nastat principialne dve zmeny:
1) pole "account_name" prestane byt funkcni (existujici, overenou) e-mailovou adresou; pokud se tak stane, budeme o tom s predstihem informovat (a tuto skutecnost dale zminime nekde v datech odpovedi)
2) pole "account_name" prestane byt unikatni. Dle meho nazoru je toto vyrazne mene pravdepodobne, nez predchozi bod. Pokud by tato neprijemna moznost nastala, tak o tom budeme taktez informovat a zaroven nabidneme nejake dalsi pole, ktere *bude* unikatni.
