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
Ostatnia wersja Both sides next revision
api_http [2014/09/26 21:47]
zozlak [Testy]
api_http [2015/06/02 21:03]
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,  
 +  * np. http://​api.ewd.edu.pl?​akcja=zwrWskazniki&​doPrezentacji=1&​rodzajWsk=ewd \\ 
 +Nie ma potrzeby autoryzacji,​ przesyłania specjalnych nagłówków,​ itp.
  
-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+
  
-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 =====+Typowy schemat korzystania z API to:
  
-Skrypty wywoływane przez klienta są cieniutkimi obudowami nad klasami, które odwalają zasadniczą robotę. Skrypt taki musi+  * wyszukanie szkół i/lub JST za pomocą //akcjizwrSzkoly, zwrGminy, zwrPowiaty, zwrWojewodztwa//,​ 
-  * zainicjalizować środowisko (dołączając plik //init.php// - znajduje się tam kod odpowiedzialny za nawiązanie połączenia ​bazą inicjalizcję automatycznego ładowacza klas); +  * wyszukanie wskaźników dostępnych dla danych szkół i/lub JST za pomocą //akcji zwrWskazniki// (odpowiednio ustawionymi parametrami //​idSzkol// ​i/lub //idJST//), 
-  * utworzyć obiekt stosownej klasy; +  * pobranie wartości wskaźników i/lub wykresów za pomocą ​//akcji: zwrDanePWE, zwrDaneEWD, zwrWykresPWE,​ zwrWykresEWD//.
-  * wykonać na nim metodę ​//wykonajZapytanie($_GET)//. +
-Patrz plik //API/teryt.php//+
  
-==== Klasy ====+Aby wywołać daną //akcję// w odpowiedni sposób, potrzeba zapoznać się z dostępnymi dla niej parametrami,​ co opisano poniżej.
  
-  * Pliki z klasami siedzą w katalogu //API/src// - każda klasa w osobnym pliku nazwanym tak samo, jak klasa, którą plik zawiera. +==== Odczytywanie listy akcji ====
-  * Każda klasa implementuje interfejs //​EWD\Prezentacja\APIInterface//,​ a więc metody: +
-    * //​zwrParametry()//​ - zwracającą opis parametrów osbługiwanych przez metodę //​obsluzZapytanie($param)//;​ +
-    * //​obsluzZapytanie(array $param)// - wykonującą kwerendę.+
  
-Patrz pliki //API/src/Teryt.php// oraz //API/src/TerytException.php//.+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>
  
-Strukturę klas oraz obsługiwane przez każdą z nich parametry kwerend będziemy sobie omawiać po kolei w ramach postępów prac nad stroną.+Ze zwróconego obiektu możemy dowiedzieć się, że API przyjmuje obowiązkowy parametr //​akcja// ​oraz jakie może on przyjąć wartości.
  
-==== Testy ====+==== Odczytywanie parametrów dostępnych dla danej akcji ====
  
-Każda klasa jest obłożona testami: +Aby dowiedzieć ​się, jakie parametry przyjmuje dana //akcja//, należy ​wywołać API ze wskazaną //akcją// oraz parametrem ​//pomoc//, np.:
-  * Testy siedzą w katalogu //​API/​tests//​ i nazywają ​się takjak 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]]+
  
 +<​code>​
 +http://​api.ewd.edu.pl?​akcja=zwrWskazniki&​pomoc=
 +</​code>​
 +W wyniku otrzymujemy opis wszystkich dostępnych parametrów. Z uwagi na jego długość, poniżej zamieszczono tylko początek
 +<​code>​
 +[
 +   {
 +      "​wartosci"​ : [
 +         "​ewd",​
 +         "​pwe"​
 +      ],
 +      "​wartDomyslna"​ : null,
 +      "​typ"​ : "​string",​
 +      "​opis"​ : "​rodzaj wskaźnika",​
 +      "​nazwa"​ : "​rodzajWsk",​
 +      "​obowiazkowy"​ : false
 +   },
 +   {
 +      "​nazwa"​ : "​doPrezentacji",​
 +      "​obowiazkowy"​ : false,
 +      "​wartDomyslna"​ : null,
 +      "​typ"​ : "​bool",​
 +      "​opis"​ : "czy tylko wskaźniki do publicznej prezentacji/​ukryte",​
 +      "​wartosci"​ : null
 +   },
 +   (...)
 +]
 +</​code>​
 +
 +===== Przykłady w językach programowania =====
 +
 +Jako przykład wykorzystane zostanie wywołanie //akcji zwrWskazniki//​ z parametrami:​
 +
 +  * //​doPrezentacji//​ równym 1;
 +  * //​rodzajWsk//​ równym //pwe//;
 +
 +http://​api.ewd.edu.pl?​akcja=zwrWskazniki&​doPrezentacji=1&​rodzajWsk=ewd
 +
 +==== jQuery ====
 +
 +<code javascript>​
 +var param = {
 +  akcja: '​zwrWskazniki',​
 +  doPrezentacji:​ 1,
 +  rodzajWsk: '​pwe'​
 +}
 +$.getJSON('​http://​api.ewd.edu.pl',​ param, function(dane){
 +   ...tu wpisz kod obsługi danych...
 +});
 +</​code>​
 +
 +==== PHP ====
 +
 +<code php>
 +$url = http_build_query(array(
 +  '​akcja'​ => '​zwrWskazniki',​
 +  '​doPrezentacji'​ => 1,
 +  '​rodzajWsk'​ => '​pwe'​
 +));
 +$dane = json_decode(file_get_contents('​http://​api.ewd.edu.pl?'​ . $url));
 +</​code>​
 +
 +==== R ====
 +
 +W R najłatwiej użyć pakietów httr oraz rjson.
 +
 +<code rsplus>
 +library(httr)
 +library(rjson)
 +dane = GET(
 +  '​http://​api.ewd.edu.pl', ​
 +  query = list(
 +    akcja = '​zwrWskazniki',​
 +    doPrezentacji = 1,
 +    rodzajWsk = '​pwe'​
 +  )
 +)
 +dane = content(dane,​ '​parsed'​)
 +</​code>​
api_http.txt · ostatnio zmienione: 2015/06/02 21:04 przez zozlak