Fórum nápovědy

Seznam

Chybějící dokumentace

Jan Janoušek

26.10.2021 v 19:46

V současné dokumentaci chybí spousta informací potřebných pro korektní implementaci. Například:
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

Dobrý den,
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

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.

Tomas Hauso

2.11.2021 v 11:05

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

Jan Janoušek reagoval na příspěvek od Ondřej Žára

2.11.2021 v 20:01

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.

Ondřej Žára reagoval na příspěvek od Tomas Hauso

3.11.2021 v 10:28

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).

Ondřej Žára reagoval na příspěvek od Jan Janoušek

3.11.2021 v 10:32

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:

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.

Nový dotaz

Přiložené přílohy

    Zbývá 12MB (z 12MB)

    Chybějící dokumentace

    Přiložené přílohy

      Zbývá 12MB (z 12MB)