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
Poprzednia wersja
api_http [2015/06/02 20:35]
zozlak
api_http [2015/06/02 21:04]
zozlak [R]
Linia 9: Linia 9:
   * generowanie wykresów EWD/PWE w formatach SVG i PNG.   * generowanie wykresów EWD/PWE w formatach SVG i PNG.
  
-Wszystkie argumenty wywołania API przekazywane są przez adres zapytania HTTP GET.+Wszystkie argumenty wywołania API przekazywane są przez adres zapytania HTTP GET,  
 +  * np. http://​api.ewd.edu.pl?​akcja=zwrWskazniki&​doPrezentacji=1&​rodzajWsk=ewd \\ 
 +Nie ma potrzeby autoryzacji,​ przesyłania specjalnych nagłówków,​ itp.
  
-Z wyjątkiem akcji generujących wykresy API zwraca kod JSON. \\  +Z wyjątkiem akcji generujących wykresy API zwraca kod JSON.
-**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.**+
  
 API dostępne jest pod adresem http://​api.ewd.edu.pl API dostępne jest pod adresem http://​api.ewd.edu.pl
  
 ===== Korzystanie z API ===== ===== Korzystanie z API =====
 +
 +Typowy schemat korzystania z API to:
 +
 +  * wyszukanie szkół i/lub JST za pomocą //akcji: zwrSzkoly, zwrGminy, zwrPowiaty, zwrWojewodztwa//,​
 +  * wyszukanie wskaźników dostępnych dla danych szkół i/lub JST za pomocą //akcji zwrWskazniki//​ (z odpowiednio ustawionymi parametrami //idSzkol// i/lub //idJST//),
 +  * pobranie wartości wskaźników i/lub wykresów za pomocą //akcji: zwrDanePWE, zwrDaneEWD, zwrWykresPWE,​ zwrWykresEWD//​.
 +
 +Aby wywołać daną //akcję// w odpowiedni sposób, potrzeba zapoznać się z dostępnymi dla niej parametrami,​ co opisano poniżej.
 +
 +==== Odczytywanie listy akcji ====
  
 Aby uzyskać listę dostępnych //akcji//, wywołaj API z parametrem //pomoc// Aby uzyskać listę dostępnych //akcji//, wywołaj API z parametrem //pomoc//
Linia 48: Linia 59:
  
 Ze zwróconego obiektu możemy dowiedzieć się, że API przyjmuje obowiązkowy parametr //akcja// oraz jakie może on przyjąć wartości. Ze zwróconego obiektu możemy dowiedzieć się, że API przyjmuje obowiązkowy parametr //akcja// oraz jakie może on przyjąć wartości.
 +
 +==== Odczytywanie parametrów dostępnych dla danej akcji ====
  
 Aby dowiedzieć się, jakie parametry przyjmuje dana //akcja//, należy wywołać API ze wskazaną //akcją// oraz parametrem //pomoc//, np.: Aby dowiedzieć się, jakie parametry przyjmuje dana //akcja//, należy wywołać API ze wskazaną //akcją// oraz parametrem //pomoc//, np.:
Linia 54: Linia 67:
 http://​api.ewd.edu.pl?​akcja=zwrWskazniki&​pomoc= http://​api.ewd.edu.pl?​akcja=zwrWskazniki&​pomoc=
 </​code>​ </​code>​
-W wyniku otrzymujemy ​kompletny ​opis wszystkich dostępnych parametrów:+W wyniku otrzymujemy opis wszystkich dostępnych parametrów. Z uwagi na jego długość, poniżej zamieszczono tylko początek
 <​code>​ <​code>​
 [ [
Linia 67: Linia 80:
       "​nazwa"​ : "​rodzajWsk",​       "​nazwa"​ : "​rodzajWsk",​
       "​obowiazkowy"​ : false       "​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 
    },    },
    {    {
Linia 163: Linia 89:
       "​wartosci"​ : null       "​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>​ </​code>​
-==== Korzystanie w jQuery ==== 
  
-Korzystanie z API z użyciem biblioteki jQuery jest bardzo ​łatwe:+===== Przykłady w językach programowania ===== 
 + 
 +Jako przykład wykorzystane zostanie wywołanie //akcji zwrWskazniki//​ z parametrami:
  
-  * najpierw tworzymy obiekt z parametrami wywołania API+  * //​doPrezentacji//​ równym 1
-  * następnie korzystamy z funkcji ​//$.getJSON()//.+  * //rodzajWsk// równym //pwe//; 
 + 
 +http://api.ewd.edu.pl?​akcja=zwrWskazniki&​doPrezentacji=1&​rodzajWsk=ewd 
 + 
 +==== jQuery ====
  
-Przytoczony wyżej przykład wyszukiwania szkół w jQuery wyglądałby tak: 
 <code javascript>​ <code javascript>​
 var param = { var param = {
 +  akcja: '​zwrWskazniki',​
 +  doPrezentacji:​ 1,
 +  rodzajWsk: '​pwe'​
 } }
 $.getJSON('​http://​api.ewd.edu.pl',​ param, function(dane){ $.getJSON('​http://​api.ewd.edu.pl',​ param, function(dane){
Linia 270: Linia 115:
 </​code>​ </​code>​
  
-==== Korzystanie w PHP ==== +==== PHP ====
  
-Przytoczony wyżej przykład wyszukiwania szkół w PHP wyglądałby tak: 
 <code php> <code php>
 $url = http_build_query(array( $url = http_build_query(array(
-  '​akcja'​ => 'zwrSzkoly',+  '​akcja'​ => 'zwrWskazniki', 
 +  '​doPrezentacji'​ => 1, 
 +  '​rodzajWsk'​ => '​pwe'​
 )); ));
 $dane = json_decode(file_get_contents('​http://​api.ewd.edu.pl?'​ . $url)); $dane = json_decode(file_get_contents('​http://​api.ewd.edu.pl?'​ . $url));
 </​code>​ </​code>​
  
-==== Korzystanie w R ====+==== R ====
  
-W R najłatwiej użyć pakietów httr oraz rjson.+W R najłatwiej użyć pakietów httr oraz jsonlite.
  
-Przytoczony wyżej przykład wyszukiwania szkół w R wyglądałby tak: 
 <code rsplus> <code rsplus>
 library(httr) library(httr)
-library(rjson)+library(jsonlite)
 dane = GET( dane = GET(
   '​http://​api.ewd.edu.pl', ​   '​http://​api.ewd.edu.pl', ​
-  akcja='​zwrSzkoly'+  ​query = list( 
 +    ​akcja = 'zwrWskazniki',​ 
 +    doPrezentacji = 1, 
 +    rodzajWsk = 'pwe' 
 +  )
 ) )
-dane = fromJSON(content(dane,​ 'text'))+dane = content(dane,​ 'parsed')
 </​code>​ </​code>​
api_http.txt · ostatnio zmienione: 2015/06/02 21:04 przez zozlak