Rozmowy o API (Stempel)

[Franklin Garamond]

Nie wiem do czego miałyby być te kody używane, ale jeśli np. można pobrać użytkownika (/api/user/{kod-jednorazowy}) i to zwraca m.in. kraje w którym jest on uwierzytelniony, to ja to bym bardzo chciał, żeby używane były id danych krajów, a które będzie można pozyskać prostym zapytaniem do api np. /api/kraje/{id} i otrzymać kraj o konkretnym id albo /api/kraje i otrzymać listę wszystkich. Dzięki temu nie będę musiał się martwić rozszerzaniem po stronie swojej aplikacji obsługi nowych krajów.

[Helwetyk Romański]

Nie wiem do czego miałyby być te kody używane, ale jeśli np. można pobrać użytkownika (/api/user/{kod-jednorazowy}) i to zwraca m.in. kraje w którym jest on uwierzytelniony, to ja to bym bardzo chciał, żeby używane były id danych krajów, a które będzie można pozyskać prostym zapytaniem do api np. /api/kraje/{id} i otrzymać kraj o konkretnym id albo /api/kraje i otrzymać listę wszystkich. Dzięki temu nie będę musiał się martwić rozszerzaniem po stronie swojej aplikacji obsługi nowych krajów.

To jest bardzo cenna uwaga (odnośnie do API dla krajów, podobnie na liście już mam API dla użytkowników). Nie wiem tylko, na ile tego typu rozszerzenie specyfikacji nie spowodowałoby trudności po stronie wdrożenia integracji. Intuicja mi podpowiada, że mogłoby.

[Franklin Garamond]

Jak mówiłem - jeśli w ramach API zwracane mają być te trójliterowe kody w jakikolwiek sposób, to bardzo bym nie chciał po stronie swojej aplikacji musieć prowadzić jakąś tablicę i aktualizować ją z każdym nowym krajem, by rozkodować ten kod.

Nie wiem tylko, na ile tego typu rozszerzenie specyfikacji nie spowodowałoby trudności po stronie wdrożenia integracji. Intuicja mi podpowiada, że mogłoby.

Nie widzę powodu dlaczego to miałoby cokolwiek skomplikować. To nie jest 100 endpointów, a ile? 4 zamiast 3?
Poza tym użycie go byłoby całkowicie fakultatywne.

[Helwetyk Romański]

Jak mówiłem - jeśli w ramach API zwracane mają być te trójliterowe kody w jakikolwiek sposób, to bardzo bym nie chciał po stronie swojej aplikacji musieć prowadzić jakąś tablicę i aktualizować ją z każdym nowym krajem, by rozkodować ten kod.

Ilość danych jest na tyle niewielka, że głośno się zastanawiam, czy nie zwracać i kodów tekstowych, i numerycznych (tu: przy równoczesnym udostępnieniu API). Mając nadzieję, że poniższy fragment nikogo nie zniechęci (staram się, aby był przyjazny w lekturze dla humanistów… i dla mnie), 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',
  ),
)

[Franklin Garamond]

A może po prostu id => nazwa? Po co są w ogóle te kody? Autor nadal tego nie ujawnił 🙄

[Helwetyk Romański]

A może po prostu id => nazwa?

W sensie, pełna (lub skrócona) nazwa kraju, z polskimi znakami etc.?

Po co są w ogóle te kody? Autor nadal tego nie ujawnił 🙄

Na okoliczność, gdyby w ramach jakiegoś przedsięwzięcia oczekiwano, że będą z niego korzystali tylko mieszkańcy danego kraju. Oczywiście, z powodów natury ideowej wolałbym, aby takich przedsięwzięć było jak najmniej, ale też i przypuszczam, że taka funkcjonalność byłaby wskazana.

[George S. Patton]

A może po prostu id => nazwa? Po co są w ogóle te kody? Autor nadal tego nie ujawnił 🙄

Dokładnie to chciałem napisać... Jak mamy ID, to po co nam jeszcze kod, skoro można zwrócić pełną nazwę, skoro i tak jest łańcuch znaków zwracany.
Oczywiście znane są przypadki, gdzie kody są stosowane, można zrzucać wręcz jako tablicę, gdzie będzie i "code" i "name" w zależności od "id"
I polskie znaki tu nie stanowią chyba?

[Helwetyk Romański]

A może po prostu id => nazwa? Po co są w ogóle te kody? Autor nadal tego nie ujawnił 🙄

Dokładnie to chciałem napisać... Jak mamy ID, to po co nam jeszcze kod, skoro można zwrócić pełną nazwę, skoro i tak jest łańcuch znaków zwracany.

Pod kątem wygody implementacji. Wiadomo, że po identyfikatorze numerycznym można rozpoznać dany kraj. Jest to liczba, którą trzeba gdzieś zapisać, pobrać — nie twierdzę, że to jest w jakimkolwiek stopniu trudne; to po prostu dodatkowy nakład pracy. 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…

Oczywiście znane są przypadki, gdzie kody są stosowane, można zrzucać wręcz jako tablicę, gdzie będzie i "code" i "name" w zależności od "id". I polskie znaki tu nie stanowią chyba?

W osobnym mechanizmie, zdecydowanie.

[George S. Patton]

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.

W osobnym mechanizmie, zdecydowanie.

Zdecydowanie polecam :)

[George S. Patton]

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.