Chybějící dokumentace
-
V současné dokumentaci chybí spousta informací potřebných pro korektní implementaci. Například:
- user_id u https://login.szn.cz/api/v1/oauth/token je jakého typu? Bude to to 32 bitové, nebo 64 bitové číslo?
- 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ý?
- 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 ?
-
Dobrý den,
také bych rád dodal, že by bylo vhodné dokumentaci rozšířit o schema objektů, které se z jednotlivých endpointů vrací. -
Dobry den,
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.
-
nove se mi user_id nevraci z v ramci GET api/v1/oauth/auth
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 -
Dobrý den,
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. -
Dobry den,
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).
-
Dobry den,
dokumentace od pocatku zminuje vyhradne e-mailovou adresu, ktera je zamyslena jako unikatni identifikator. V budoucnu v teto veci mohou nastat principialne dve zmeny:
-
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)
-
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.
-