Rozmowy o API (Stempel)

[George S. Patton]

Ostatnia wiadomość z poprzedniej strony wątku

tak wygląda roboczo rezultat odpytania Stempla przy użyciu mojego hasła jednorazowego:

Kod: Zaznacz cały

array (
  'blad' => 'BRAK_BLEDU',
  'dane' => 
    array (
      'paszport' => 1000,
      'personalia' => 'Helwetyk Romański',
      'profil' => 'https://stempel.org.pl/paszport/1000',
      'awatar' => 'https://stempel.org.pl/fotografie/miniatury/16055602681352291778.png',
    ),
  'kraje_kody' => 
    array (
      8 => 'AUH',
      7 => 'BIA',
      11 => 'BIZ',
      5 => 'BRO',
      2 => 'DRE',
      1 => 'LEO',
      3 => 'RON',
      6 => 'ROT',
      4 => 'SAR',
      9 => 'SKA',
      10 => 'WIN',
  ),
)

Hm, ja bym zrobił jakoś tak:

Kod: Zaznacz cały

{
	status: int,
	data: {
		// jakieś tam dane
	},
	countries: {
		// jeżeli trzeba
	}
}

Bo dzięki temu status jak jest np. 0 to brak błędu, jak 1 to błąd. Albo wręcz można skorzystać ze statusów HTTP, dać 200 na ok, 404 na nie znaleziono, 403 na zabronione itp.

[Helwetyk Romański]

W przypadku kodu literowego wystarczy szybkie sprawdzenie typu czy_tablica_zawiera_kod('LEO') i można pójść dalej. A dlaczego sam kod? Ponieważ kraje zmieniają nazwy…

No tak, to jeszcze szybciej będzie if ( 1 === id_kraju ) i mamy, że Leocja.

Owszem, dla niehumanistów. Dla normalnych ludzi (#musiałem) łatwiejsze będzie if ( kod_kraju === LEO ).

[George S. Patton]

Owszem, dla niehumanistów. Dla normalnych ludzi (#musiałem) łatwiejsze będzie if ( kod_kraju === LEO ).

No ale dopóki nie zrobimy:

Kod: Zaznacz cały

const LEO = 1;

lub

Kod: Zaznacz cały

define( __NAMESPACE__ . '\LEO', 1 );

...to inaczej to normalnym (#wiem) nie zadziała. Tak że tego. Humanizm jak najbardziej, ale umówmy się, kod będą pisać jednak ludzie, którzy chociaż wiedzą, gdzie go wpisać i wstawić. A instrukcja jakaś, jak się domyślam, będzie?

[Helwetyk Romański]

Hm, ja bym zrobił jakoś tak: […]

Oczywiście, w złym miejscu wpiąłem dane o autoryzacji krajowej, powinny znajdować się w tabeli ze zwracanymi danymi mieszkańca — dziękuję za mimowolne zwrócenie uwagi. Z tym zastrzeżeniem, nie chcę zwracać numerycznych (albo wyłącznie numerycznych) kodów błędu, ponieważ #humanizm. Kod tekstowy można od razu wyświetlić i wiedzieć, co nie zabanglało.

No ale dopóki nie zrobimy: […]

Szalenie szanuję poprawienie mojego pseudokodu! 😍

Humanizm jak najbardziej, ale umówmy się, kod będą pisać jednak ludzie, którzy chociaż wiedzą, gdzie go wpisać i wstawić. A instrukcja jakaś, jak się domyślam, będzie?

Będzie, ale w równym stopniu liczyłbym na wsparcie szeroko rozumianej społeczności. Tym niemniej, im mniejsze wymagania dla implementacji, tym lepiej.

[George S. Patton]

Oczywiście, w złym miejscu wpiąłem dane o autoryzacji krajowej, powinny znajdować się w tabeli ze zwracanymi danymi mieszkańca — dziękuję za mimowolne zwrócenie uwagi.

Zawsze do usług Czcigodny Namiestniku :)

Kod tekstowy można od razu wyświetlić i wiedzieć, co nie zabanglało.

Błąd, to błąd, im bardziej ogólny, tym bezpieczniej.
Użytkownik nie musi wiedzieć co się dzieje, twórca aplikacji ma wiedzieć.
I dzięki temu zwracamy zawsze inta, co pozwala na większą konsekwencję.
Oczywiście można dać zawsze łańcuch i dawać "OK" oraz "Cokolwiek innego, co jest błędem".
Mnie to razi, no ale.

Szalenie szanuję poprawienie mojego pseudokodu! 😍

Trzeba było nie pisać "===" :) To bym to brał za pseudokod :)

Będzie, ale w równym stopniu liczyłbym na wsparcie szeroko rozumianej społeczności. Tym niemniej, im mniejsze wymagania dla implementacji, tym lepiej.

No, to tabelka z kod kraju, nazwa kraju - i jest.

[Helwetyk Romański]

Kod tekstowy można od razu wyświetlić i wiedzieć, co nie zabanglało.

Błąd, to błąd, im bardziej ogólny, tym bezpieczniej. Użytkownik nie musi wiedzieć co się dzieje, twórca aplikacji ma wiedzieć. I dzięki temu zwracamy zawsze inta, co pozwala na większą konsekwencję.

Tutaj już wchodzimy w sferę filozofii systemu. Nie zakładam różnicy między twórcą a użytkownikiem aplikacji innej niż ta, że twórca chciał coś zintegrować ze Stemplem, a użytkownik — nie. Co więcej, jeżeli komunikat błędu będzie publiczny, łatwiej będzie zgłaszać błędy. Bezpieczeństwo, w warunkach mikronacyjnych, jest ważne, ale nie jest priorytetem. Chodzi o zabawę w możliwie najszerszym gronie. Tym samym…

Oczywiście można dać zawsze łańcuch i dawać "OK" oraz "Cokolwiek innego, co jest błędem". Mnie to razi, no ale.

…zwracałbym łańcuchy, roboczo są następujące: BRAK_KLUCZA, ZLY_FORMAT_KLUCZA, BLEDNY_KLUCZ, BRAK_HASLA, ZLY_FORMAT_HASLA, BLEDNE_HASLO, HASLO_WYKORZYSTANE, BRAK_BLEDU.

[George S. Patton]

Tym samym…

Z tym nie podyskutuję Czcigodny, ale swoje zdanie sobie skrzętnie zachowam.

…zwracałbym łańcuchy, roboczo są następujące: BRAK_KLUCZA, ZLY_FORMAT_KLUCZA, BLEDNY_KLUCZ, BRAK_HASLA, ZLY_FORMAT_HASLA, BLEDNE_HASLO, HASLO_WYKORZYSTANE, BRAK_BLEDU.

Oczy mi krwawią i łzawią :)
To skoro to ma być użytkownikowi wyświetlane, to może już napisać
"Brak klucza", "Zły format klucza", "Błędny klucz", "Brak hasła", "Zły format hasła", "Błędne hasło", "Hasło wykorzystane" i "Brak błędu"?

To ładniej wygląda wyświetlone.

[Helwetyk Romański]

…zwracałbym łańcuchy, roboczo są następujące: BRAK_KLUCZA, ZLY_FORMAT_KLUCZA, BLEDNY_KLUCZ, BRAK_HASLA, ZLY_FORMAT_HASLA, BLEDNE_HASLO, HASLO_WYKORZYSTANE, BRAK_BLEDU.

To skoro to ma być użytkownikowi wyświetlane, to może już napisać "Brak klucza", "Zły format klucza", "Błędny klucz", "Brak hasła", "Zły format hasła", "Błędne hasło", "Hasło wykorzystane" i "Brak błędu"? To ładniej wygląda wyświetlone.

Wygląda… Tablica, w której numeryczny indeks jest kodem błędu, a wartość „ładnym” komunikatem? 🤔

[George S. Patton]

Wygląda… Tablica, w której numeryczny indeks jest kodem błędu, a wartość „ładnym” komunikatem? 🤔

No można oczywiście tak, ale ja mówię o tym, co zwraca API.
Niech zwróci stringa, ale skoro to już ma być "ZLE_HASLO" to czemu nie "Złe hasło"?
Porównanie stringów takie samo.

[George S. Patton]

Albo wręcz, możemy się pogodzić.
Zwracać może tak:

Kod: Zaznacz cały

status: {
    code: 0,
    message: "Brak błędu",
}

Czy też:

Kod: Zaznacz cały

status: {
    code: 1,
    message: "Złe hasło",
}

itd. Dzięki temu mamy i kod numeryczny i ładne wyświetlenia. Oczywiście nie może zabraknąć propozycji dla pół-humanistów...

Kod: Zaznacz cały

status: {
    code: 1,
    semiHumanist: "ZLE_HASLO",
    message: "Złe hasło",
}

:D

[Helwetyk Romański]

Albo wręcz, możemy się pogodzić. Zwracać może tak: […]

O, i tak będzie super! (Po przełożeniu na polski ;-)).