Narzędzia użytkownika

Narzędzia witryny


api_http

Różnice

Różnice między wybraną wersją a wersją aktualną.

Odnośnik do tego porównania

Both sides previous revision Poprzednia wersja
Nowa wersja Both sides next revision
api_http [2014/09/26 21:47]
zozlak [Testy]
api_http [2015/06/02 20:35]
zozlak
Linia 1: Linia 1:
-====== API HTTP - jak to działa ​======+====== API HTTP bazy ======
  
-===== Od strony klienta =====+Baza udostępnia proste API HTTP umożliwiające:​
  
-Za pomocą odpowiednio przygotowanego zapytania HTTP GET klient wykonuje kwerendę na bazie danych.+  * wyszukiwanie szkół; 
 +  * wyszukiwanie jednostek samorządu terytorialnego (JST); 
 +  * wyszukiwanie wskaźników;​ 
 +  * pobieranie ​danych ​EWD/PWE; 
 +  * generowanie wykresów EWD/PWE w formatach SVG i PNG.
  
-Wynik otrzymuje w formacie JSON.+Wszystkie argumenty wywołania API przekazywane są przez adres zapytania HTTP GET.
  
-góry zna (bo gdzieś będzie stosowna lista) adresy skryptów wykonujących ​poszczególne kwerendy, np+wyjątkiem akcji generujących ​wykresy API zwraca kod JSON\\  
-  http://ewd.edu.pl/API/teryt.php+**W zamieszczonych przykładach zwracany kod JSON będzie ładnie sformatowany,​ tak by widać było strukturę obiektów. \\ //Surowy// kod JSON nie wygląda tak ładnie.**
  
-Każdy skrypt obsługuje pogrupowaną tematycznie rodzinę kwerend. O tym, jakie to są kwerendy i jakie przyjmują parametry klient może dowiedzieć się wywołując dany skrypt bez żadnych parametrów. W wyniku dostanie JSON-a z ich listą i opisem (np. http://​ewd.edu.pl/​API/​teryt.php).+API dostępne jest pod adresem ​http://api.ewd.edu.pl
  
-Znając dostępne parametry klient może przygotować stosowne wywołanie HTTP GET, które wykona oczekiwaną kwerendę( +===== Korzystanie z API =====
-np. pobieramy wszystkie powiaty w województwie Mazowieckim wg stanu na 2014 r. http://​ewd.edu.pl/​API/​teryt.php?​akcja=zwrPowiaty&​rok=2014&​id_wojewodztwa=14+
  
-===== Od strony serwera =====+Aby uzyskać listę dostępnych //akcji//, wywołaj API z parametrem //pomoc// 
 +<​code>​ 
 +http://​api.ewd.edu.pl?​pomoc= 
 +</​code>​ 
 +<​code>​ 
 +
 +   { 
 +      "​obowiazkowy"​ : true, 
 +      "​typ"​ : "​string",​ 
 +      "​wartDomyslna"​ : null, 
 +      "​nazwa"​ : "​akcja",​ 
 +      "​opis"​ : "Akcja API",​ 
 +      "​wartosci"​ : [ 
 +         "​zwrWskazniki",​ 
 +         "​zwrDanePWE",​ 
 +         "​zwrCSVPWE",​ 
 +         "​zwrWykresPWE",​ 
 +         "​zwrDaneAdrSzkoly",​ 
 +         "​zwrDaneEWD",​ 
 +         "​zwrWykresEWD",​ 
 +         "​zwrSzkoly",​ 
 +         "​zwrWojewodztwa",​ 
 +         "​zwrPowiaty",​ 
 +         "​zwrGminy"​ 
 +      ] 
 +   } 
 +
 +</​code>​
  
-Skrypty wywoływane przez klienta są cieniutkimi obudowami nad klasamiktóre odwalają zasadniczą robotę. Skrypt taki musi: +Ze zwróconego obiektu możemy dowiedzieć sięże API przyjmuje obowiązkowy parametr ​//akcja// oraz jakie może on przyjąć wartości.
-  * zainicjalizować środowisko (dołączając plik //init.php// - znajduje się tam kod odpowiedzialny za nawiązanie połączenia z bazą i inicjalizcję automatycznego ładowacza klas); +
-  * utworzyć obiekt stosownej klasy; +
-  * wykonać na nim metodę //​wykonajZapytanie($_GET)//​. +
-Patrz plik //​API/​teryt.php//​+
  
-==== Klasy ====+Aby dowiedzieć się, jakie parametry przyjmuje dana //akcja//, należy wywołać API ze wskazaną //akcją// oraz parametrem //pomoc//, np.:
  
-  * Pliki z klasami siedzą w katalogu ​//API/src// - każda klasa w osobnym pliku nazwanym tak samojak klasaktórą plik zawiera. +<​code>​ 
-  * Każda klasa implementuje interfejs //​EWD\Prezentacja\APIInterface//​a więc metody+http://api.ewd.edu.pl?​akcja=zwrWskazniki&​pomoc= 
-    ​* ​//​zwrParametry()//​ - zwracającą ​opis parametrów osbługiwanych przez metodę //​obsluzZapytanie($param)//; +</code> 
-    * //​obsluzZapytanie(array $param)// - wykonującą kwerendę.+W wyniku otrzymujemy kompletny opis wszystkich dostępnych parametrów:​ 
 +<​code>​ 
 +
 +   { 
 +      "​wartosci"​ : [ 
 +         "​ewd"​, 
 +         "​pwe"​ 
 +      ], 
 +      "​wartDomyslna"​ : null, 
 +      "​typ"​ : "​string",​ 
 +      "​opis"​ : "​rodzaj wskaźnika",​ 
 +      "​nazwa"​ : "​rodzajWsk",​ 
 +      "​obowiazkowy"​ : false 
 +   }, 
 +   { 
 +      "​obowiazkowy"​ : false, 
 +      "​nazwa"​ : "​wskaznik",​ 
 +      "​typ"​ : "​[string]",​ 
 +      "​opis"​ : "nazwy wskaźników",​ 
 +      "​wartDomyslna"​ : null, 
 +      "​wartosci"​ : [ 
 +         "​gh",​ 
 +         "​gh_bt",​ 
 +         "​gh_bt_mod",​ 
 +         "​gh_h_bt_mod",​ 
 +         "​gh_mod",​ 
 +         "​gh_p_bt_mod",​ 
 +         "​gh_przed2011",​ 
 +         "​gh_w11",​ 
 +         "​gh_w11_bt",​ 
 +         "​gm_m_bt_mod",​ 
 +         "​gmp",​ 
 +         "​gmp_bt",​ 
 +         "​gm_p_bt_mod",​ 
 +         "​gmp_bt_mod",​ 
 +         "​gmp_mod",​ 
 +         "​gmp_przed2011",​ 
 +         "​gmp_w11",​ 
 +         "​gmp_w11_bt",​ 
 +         "​mlh_dl",​ 
 +         "​mlh_tl",​ 
 +         "​mlh_tl_mod",​ 
 +         "​mlh_tl_wgr",​ 
 +         "​mlm_dl",​ 
 +         "​mlm_jr",​ 
 +         "​mlmp_dl",​ 
 +         "​mlmp_tl",​ 
 +         "​mlmp_tl_mod",​ 
 +         "​mlmp_tl_wgr",​ 
 +         "​mlm_tl",​ 
 +         "​mlm_tl_mod",​ 
 +         "​mlm_tl_wgr",​ 
 +         "​mlp_dl",​ 
 +         "​mlp_jr",​ 
 +         "​mlp_tl",​ 
 +         "​mlp_tl_mod",​ 
 +         "​mlp_tl_wgr",​ 
 +         "​mth_dl",​ 
 +         "​mth_tl",​ 
 +         "​mth_tl_mod",​ 
 +         "​mth_tl_wgr",​ 
 +         "​mtm_dl",​ 
 +         "​mtm_jr",​ 
 +         "​mtmp_dl",​ 
 +         "​mtmp_tl",​ 
 +         "​mtmp_tl_mod",​ 
 +         "​mtmp_tl_wgr",​ 
 +         "​mtm_tl",​ 
 +         "​mtm_tl_mod",​ 
 +         "​mtm_tl_wgr",​ 
 +         "​mtp_dl",​ 
 +         "​mtp_jr",​ 
 +         "​mtp_tl",​ 
 +         "​mtp_tl_mod",​ 
 +         "​mtp_tl_wgr",​ 
 +         "​paou_gh",​ 
 +         "​paou_gh_pierw",​ 
 +         "​paou_gh_war",​ 
 +         "​paou_gmp",​ 
 +         "​paou_gmp_pierw",​ 
 +         "​paou_gmp_war",​ 
 +         "​paou_m_ang_pierw",​ 
 +         "​paou_m_ang_var",​ 
 +         "​paou_m_ang_war",​ 
 +         "​paou_m_mat_pierw",​ 
 +         "​paou_m_mat_var",​ 
 +         "​paou_m_mat_war",​ 
 +         "​paou_m_pol_var",​ 
 +         "​paou_m_pol_war",​ 
 +         "​paou_sp",​ 
 +         "​paou_sp_war"​ 
 +      ] 
 +   }, 
 +   { 
 +      "​obowiazkowy"​ : false, 
 +      "​nazwa"​ : "​okresy",​ 
 +      "​wartosci"​ : null, 
 +      "​opis"​ : "​okresy,​ dla których wskaźniki mają wartości",​ 
 +      "​typ"​ : "​[string]"​, 
 +      "​wartDomyslna" ​null 
 +   }, 
 +   { 
 +      "​nazwa"​ : "​doPrezentacji",​ 
 +      "​obowiazkowy"​ : false, 
 +      "​wartDomyslna"​ : null, 
 +      "​typ"​ : "​bool",​ 
 +      "​opis"​ : "czy tylko wskaźniki do publicznej prezentacji/ukryte",​ 
 +      "​wartosci"​ : null 
 +   }, 
 +   { 
 +      "​wartDomyslna"​ : null, 
 +      "​typ"​ : "​[int]",​ 
 +      "opis" : "​identyfikatory szkół, dla których mają zostać pobrane wskaźniki",​ 
 +      "​wartosci"​ : null, 
 +      "​nazwa"​ : "​idSzkol",​ 
 +      "​obowiazkowy"​ : false 
 +   }, 
 +   { 
 +      "​nazwa"​ : "​idJST",​ 
 +      "​obowiazkowy"​ : false, 
 +      "​wartosci"​ : null, 
 +      "​wartDomyslna"​ : null, 
 +      "​typ"​ : "​[int]",​ 
 +      "​opis"​ : "kody TERYT JST, dla których mają zostać pobrane wskaźniki ​(istotne tylko dla wskaźników PWE)" 
 +   }, 
 +   { 
 +      "​wartosci"​ : null, 
 +      "​wartDomyslna"​ : false, 
 +      "​opis"​ : "czy pobierać wskaźniki dla Polski ​(istotne tylko dla wskaźników PWE)", 
 +      "​typ"​ : "​bool",​ 
 +      "​nazwa"​ : "​polska",​ 
 +      "​obowiazkowy"​ : false 
 +   }, 
 +   { 
 +      "​obowiazkowy"​ : false, 
 +      "​nazwa"​ : "​typSzkoly",​ 
 +      "​wartosci"​ : [ 
 +         "​gimn.",​ 
 +         "​LO",​ 
 +         "​LOU",​ 
 +         "​LP",​ 
 +         "​SP",​ 
 +         "​T",​ 
 +         "​TU",​ 
 +         "​ZZ"​ 
 +      ], 
 +      "​typ"​ : "​string",​ 
 +      "​opis"​ : "typ szkoły, dla którego liczone są wskaźniki",​ 
 +      "​wartDomyslna"​ : null 
 +   }, 
 +   { 
 +      "​nazwa"​ : "​ewdMin",​ 
 +      "​obowiazkowy"​ : false, 
 +      "​wartDomyslna"​ : null, 
 +      "​opis"​ : "​najmniejsza dopuszczalna wartość EWD wśród wyliczonych wskaźników",​ 
 +      "​typ"​ : "​float",​ 
 +      "​wartosci"​ : null 
 +   }, 
 +   { 
 +      "​nazwa"​ : "​ewdMax",​ 
 +      "​obowiazkowy"​ : false, 
 +      "​wartosci"​ : null, 
 +      "​wartDomyslna"​ : null, 
 +      "​typ"​ : "​float",​ 
 +      "​opis"​ : "największa dopuszczalna wartość EWD wśród wyliczonych wskaźników"​ 
 +   }, 
 +   { 
 +      "​typ"​ : "​float",​ 
 +      "​opis"​ : "​najmniejszy dopuszczalny średni wynik egzaminu wśród wyliczonych wskaźników",​ 
 +      "​wartDomyslna"​ : null, 
 +      "​wartosci"​ : null, 
 +      "​obowiazkowy"​ : false, 
 +      "​nazwa"​ : "​egzMin"​ 
 +   }, 
 +   { 
 +      "​typ"​ : "​float",​ 
 +      "​opis"​ : "​największy dopuszczalny średni wynik egzaminu wśród wyliczonych wskaźników",​ 
 +      "​wartDomyslna"​ : null, 
 +      "​wartosci"​ : null, 
 +      "​obowiazkowy"​ : false, 
 +      "​nazwa"​ : "​egzMax"​ 
 +   }, 
 +   { 
 +      "​nazwa"​ : "​luMin",​ 
 +      "​obowiazkowy"​ : false, 
 +      "​wartosci"​ : null, 
 +      "​wartDomyslna"​ : null, 
 +      "​typ"​ : "​float",​ 
 +      "​opis"​ : "​najmniejsza dopuszczalna liczba uczniów wyliczonych wskaźników"​ 
 +   }, 
 +   { 
 +      "​wartosci"​ : null, 
 +      "​wartDomyslna"​ : null, 
 +      "​typ"​ : "​float",​ 
 +      "​opis"​ : "​największa dopuszczalna liczba uczniów wśród wyliczonych wskaźników",​ 
 +      "​nazwa"​ : "​luMax",​ 
 +      "​obowiazkowy"​ : false 
 +   } 
 +
 +</​code>​ 
 +==== Korzystanie w jQuery ====
  
-Patrz pliki //API/​src/​Teryt.php//​ oraz //​API/​src/​TerytException.php//​.+Korzystanie z API z użyciem biblioteki jQuery jest bardzo łatwe:
  
-Strukturę klas oraz obsługiwane przez każdą ​nich parametry kwerend będziemy sobie omawiać po kolei w ramach postępów prac nad stroną.+  * najpierw tworzymy obiekt z parametrami wywołania API; 
 +  * następnie korzystamy ​funkcji //​$.getJSON()//​.
  
-==== Testy ====+Przytoczony wyżej przykład wyszukiwania szkół w jQuery wyglądałby tak: 
 +<code javascript>​ 
 +var param 
 +
 +$.getJSON('​http://​api.ewd.edu.pl',​ param, function(dane){ 
 +   ...tu wpisz kod obsługi danych... 
 +}); 
 +</​code>​
  
-Każda klasa jest obłożona testami: +==== Korzystanie ​PHP ====
-  * Testy siedzą ​katalogu //​API/​tests//​ i nazywają się tak, jak nazwy klas, które testują z sufiksem //Test// (patrz plik //​API/​tests/​TerytTest.php//;​ +
-  * Testy uruchamiamy wywołując w katalogu //​API//<​code>​phpunit -c tests/​testy.xml tests/​nazwaPlikuTestow.php</​code>​ +
-    * po wykonaniu testów w katalogu //​API/​tests/​raporty_pokrycia//​ mamy do dyspozycji raporty pokrycia kodu. +
-  * Chcąc odpalić wszystkie testy naraz uruchamiamy w katalogu //​API//<​code>​phpunit -c tests/​testy.xml tests/</​code>​ +
-  * Więcej o pisaniu testów w [[https://​phpunit.de/​manual/​3.7/​en/​index.html|dokumentacji PHPUnit]]+
  
 +
 +Przytoczony wyżej przykład wyszukiwania szkół w PHP wyglądałby tak:
 +<code php>
 +$url = http_build_query(array(
 +  '​akcja'​ => '​zwrSzkoly',​
 +));
 +$dane = json_decode(file_get_contents('​http://​api.ewd.edu.pl?'​ . $url));
 +</​code>​
 +
 +==== Korzystanie w R ====
 +
 +W R najłatwiej użyć pakietów httr oraz rjson.
 +
 +Przytoczony wyżej przykład wyszukiwania szkół w R wyglądałby tak:
 +<code rsplus>
 +library(httr)
 +library(rjson)
 +dane = GET(
 +  '​http://​api.ewd.edu.pl', ​
 +  akcja='​zwrSzkoly'​
 +)
 +dane = fromJSON(content(dane,​ '​text'​))
 +</​code>​
api_http.txt · ostatnio zmienione: 2015/06/02 21:04 przez zozlak