API webes API a gyakorlatban Konstantinusz Kft. 2011
1. Tartalomjegyzék 1. Tartalomjegyzék... 2 2. Bevezetés... 2 3. Mi is az API?... 3 3.1. A Facebook API:... 3 3.2. Google analytics... 5 4. Saját API írása... 6 4.1. Kommunikáció... 6 4.2. Biztonság... 7 4.3. Zend keretrendszer... 8 2. Bevezetés Napjainkban nagy népszerűségnek örvendenek a web2.0 névvel illetett weboldalak. Némely közösségi oldal jóval több felhasználóval rendelkezik mint Magyarország lakossága. Ezért sok oldal próbál meg valmiféle közösséget teremteni az oldalán. Ám azonban chat és fórum fejlesztésre nem minden cégnek van erőforrása. Szintén népszerű téma ma, hogy hogyan lehet egy oldal látogatottságát növelni, vagy a látogatókat rávenni arra, hogy vásároljanak az oldalon. Ennek megállapításához szükség van arra, hogy tudjuk, hogy ki jön az oldalra meddig marad, mit csinál az oldalon, eehhez gyakran összetett programokra lehet szükség. Ezeknek a kifejlesztése sem gazdaságos az esetek többségében. Ezen kívül bizonyos esetekben előfordulhat, hogy két rendszer különböző szervereken fut, de mégis kommunikálniuk kell egymással. Jó példa erre, egy webshop és egy vállalat irányítási rendszer. Vagy két vállalat irányítási rendszer, erre jó példa egy nagyobb áruház és beszállító rendszerének összekötése. A beszállító saját rendszerében rögzíti milyen árut ad át, a megrendelő pedig saját rendszerében látja, hogy miből mennyi fog érkezni, ez rengeted időt (humán munkát) takarít meg mindkét oldalon. Az esettanulmányban példákon keresztül mutatom be, hogy miket értenek API alatt. -2-9
3. Mi is az API? Mozaik szó: API = Application Programming Interface. A nevéből kiderül, hogy az API egy felület amin keresztül az adott alkalmazás programozható. Az API olyan a programok számára min az UI (User Interface - Felhasználói felület) a felhasználó számára. Aki már foglalkozott programozással az szinte biztosan találkozott már API-val. Ha Windows alá készítünk programokat akkor is API-t használunk ez az úgynevezett Windows API. Ha valamilyen grafikus játékot készítünk, ami támogat DirectX-et, akkor biztosan DirectX API-t használunk. Saját meglátásom szerint az a Windows operációs rendszer sikerének titka, hogy egységes API-t ad programozóknak. Vagyis az így megírt programok széleskörben használhatóak. A bevezetésben említett témákat is API-nak szokás hívni annak ellenére nem minden lépése hasonlít a klasszikus értelemben vett API-hoz. Ennek a weboldalak speciális helyzete az oka. Bizonyos funkcióknak akkor kell lefutnia amikor a látogató a weboldalon tartózkodik. Ekkor a weboldal először lefut szerveren, és ennek a kimenete kerül a felhasználóhoz (ez az amit lát). És néhány funkciónak a felhasználó gépén kell lefutnia (HTML, és a JavaScript). Például: ha azt akarjuk mérni, hogy egy adott lapot mennyi ideig olvas vagy néz a látogató azt csak a látogató gépén lehet, hiszen a szerveren lefut a kód, elkészíti a kimenetet, és utána kiürül a memóriából, vagyis nem fut addíg amíg a felhasználó az oldalon van. 3.1. A Facebook API: A balépés alakamával nem klasszikus APIval van dolgunk hiszen ez esetben nem nekünk küldi el a felhasználó a belépési adatait, amivel a mi programunk lép be a Facebookra, hanem a Facebookon belép utána nekünk hozzáférésünk van bizonyos adataihoz. Az adatok lekérdezése viszont már API-n keresztül történik. Nem klasszikus API megoldás: <div id="fb-root"></div> <script src="http://connect.facebook.net/en_us/all.js"></script> <script> FB.init({ appid:'your_app_id', cookie:true, status:true, xfbml:true ); </script> -3-9
<fb:login-button>login with Facebook</fb:login-button> Ebben a példában látszik, hogy gyakorlatilag egy javaskriptet be kell tenni az oldalba és egy elemet amelyen belülre bekerül a belépés, gomb. A belépés teljesen a Facebook oldalán történik, és nem sok beleszólásunk van belépés után beállítástól függően, hozzáférünk a felhasználó bizonyos adataihoz. Amikor azonban a felhasználó adatait kérdezzük le akkor már klasszikus értelemben vett API-t kell alakalmaznunk. Egy PHP-s példa: <?php define('your_app_id', 'your application id '); define('your_app_secret', 'your application secret'); function get_facebook_cookie($app_id, $application_secret) { $args = array(); parse_str(trim($_cookie['fbs_'. $app_id], '\\"'), $args); ksort($args); $payload = ''; foreach ($args as $key => $value) { if ($key!= 'sig') { $payload.= $key. '='. $value; if (md5($payload. $application_secret)!= $args['sig']) { return null; return $args; $cookie = get_facebook_cookie(facebook_app_id, FACEBOOK_SECRET); $user = json_decode(file_get_contents( 'https://graph.facebook.com/me?access_token='. $cookie['access_token']));?> A fenti kód lefutása után a $user tartalmazza a belépett felhasználó adatait. Látható benne, hogy a kód lekérést küld a https://graph.facebook.com/me -oldalnak, átadva egy azonosítót, és visszakapja a felhasználó adatait. Részletes leírás, az implementálásról angolul: http://developers.facebook.com/docs/guides/web -4-9
3.2. Google analytics Alapvetően a látogatók tevékenységét követi. Ahhoz, hogy működjön itt sem API-ra van szükség csak egy kódot kell elhelyezni az oldalon. Követő kód: <script type="text/javascript"> var _gaq = _gaq []; _gaq.push(['_setaccount', 'YOUR_ACCOUNT_ID']); _gaq.push(['_setdomainname', 'none']); _gaq.push(['_setallowlinker', true]); _gaq.push(['_trackpageview']); (function() { var ga = document.createelement('script'); ga.type = 'text/javascript'; ga.async = true; ga.src = ('https:' == document.location.protocol? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; var s = document.getelementsbytagname('script')[0]; s.parentnode.insertbefore(ga, s); )(); </script> Ennek alkalmazása esetén az oldalba elhelyezett kód küld lekéréseket a googleanalytics.com- irányába. Ennek valószínü az is az oka, hogy így könnyebb elhelyezni az oldalba. hiszen csak a fenti kódok kell bemásolni, és már működik is. Ehhez is tartozik API amely segítségével az összesített adatok lekérdezhetőek, vagy extra adatok rögzíthetőek. Erre példa: az oldalunk egy banner megjelenéseinek száma is követhető Google analytics segítségével. Ehhez szintén javascript hívásra van szükség: <script type="text/javascript"> _trackevent(category, action, opt_label, opt_value); </script> Bővebb információ: http://code.google.com/apis/analytics/docs/tracking/eventtrackerguide.html -5-9
4. Saját API írása Mielőtt hozzákezdünk a fejlesztéshez, már célszerű meghatározni, hogy a készülő rendszerünk API-jának milyen funkciókat célszerű elérnie. Az API írásakor rendkívüli módon megkönnyítjük a saját dolgunkat, ha MCV (Model Controller View) és Objektum orientált filozófiát követünk. Ez esetben ugyanis az API-ban csak azt kell meghatároznunk, hogy a model objektumok közül melyiknek milyen funkciói érhetőek el, és hogy hogyan. Webes környezethez a legegyszerűbb megoldás ha a HTTP-n keresztül valósítjuk meg a kommunikációt ekkor nem kell bajlódni azzal, hogy hogyan írjuk meg szervert, vagy a klienst. Ez esetben a szerver részét, amely fogadja az API kéréseket, felfoghatjuk, úgy mint egy weboldalt. Amely POST paraméterként megkapja a kérést, és kimenetet generál adott formátumban. A klienshez pedig a beépített HTTP eszközt használhatjuk, PHP alatt ez a curl. Ekkor csak annyi a dolgunk, hogy a kérésünket POST-al elküldjük, és a választ megkapjuk egyszerűen, nem kell foglalkoznunk a hálózati kommunikáció felépítésével. Webes környezetben az egyszerűbb hibakeresés miatt az API-k többsége szöveges üzenetekből áll. A példákban PHP-s példákat fogok szerepeltetni, de az API nem köti meg a kezünket, ilyen kommunkációt, egy JAVA-s és egy C++ -os program között is meglehet valósítani. 4.1. Kommunikáció Erre tipikus példa, hogy XML használatával kommunkál a két program: <?xml version="1.0" encoding="utf-8"?> <methodresponse> <params> <param> <value> <boolean>1</boolean> </value> </param> </params> </methodresponse> Látható, hogy ez egy válasz üzenet ami gyakorlatilag annyit tartalmaz, hogy a kérdésre a válasz true azaz 1. -6-9
Az XML hátránya ilyen szempontból, hogy nagyon meg tudja növelni az átküldendő adat mennyiséget, hiszen itt 1 bit helyett 170 byte-ot küld vissza. Viszont tudjuk, hogy a válasz típusa boolean, és 1 ami a programozásban true-nak felel meg. Mielőtt azonban saját programunk mellé API-t kezdenénk fejleszteni, ami elég komoly fejlesztés is lehet, a funkcióktól függően, gondoljuk át, hogy mire is van igazán szükségünk. Az egyik legegyszerűbb módszer, hogy az API-n keresztül, olyan üzeneteket fogadunk amit egyből model hívásokra fordítunk le. Pl.: Azt szeretnénk egy webshoptól API-n keresztül lekérdezni, hogy mekkora értékű a 3. azonosítójú rendelés. Ez kódszinten pl: az alábbi módon nézhet ki: $rendeles = RendelesFactory::getRendeles(3); $osszeg = $rendeles->getrendelesosszeg(); API-n keresztül valahogy így lehet elképzelni: <?xml version="1.0"?> <methodcall> <methodname>rendeles.getrendelesosszeg</methodname> <params> <param> <value><id>3</id></value> </param> </params> </methodcall> Ebből az általunk megírt program tudja, hogy a 3. idvel rendelkező rendelés Objektumnak meg kell hívni a getrendelesosszeg metódusát és visszaadni az eredményt. De természetesen bárhogy variálható, az Objektum nevét ki lehet emelni külön paraméterként is. 4.2. Biztonság API irásakor figyeljünk a biztonságrais, vagyis az API-n keresztül elérhető funkciók használatához követeljük meg ugyanazokat a feltételeket, amiket a felhasználói felületen keresztül is megkövetelünk a felhasználótól. Például egy webshop esetén terméket csak adminisztrátor jogú felhasználó vehessen fel és ne bárki. Erre azért van szükség mert ha ezeket kihagyuk és valaki megtalálja az API felületünket bármilyen adatot kinyerhet a rendszerből vagy megváltoztathat. Ha itt elérhetőek olyan funkciók, hogy alkalmazás törlése, vagy lekérdezhető az adatbázis hozzáférés akkor nagy veszélynek tesszük ki rendszerünket. -7-9
Célszerű API-esetében is bejelentkezést kérni. Felhasználónév és jelszó, API esetében előfordul, hogy ugyanezeket API azonosítónak, és API kulcsnak hívják. 4.3. Zend keretrendszer Napjainkban egyre többször találkozom azzal, hogy a programozók valamilyen keretrendszerben programoznak, és nem önmaguk írják meg a programjaikat az alapoktól. Ennek a módszernek megvannak az előnyei, nem kell minden magunknak kifejleszteni, kitalálni. Valamint a programozót belekényszeríti jól bevált módszerek követésébe (Objektum orientáltáság, Model Controller View). Ezért kezdőknek javaslom, hogy valamilyen keretrendszerrel ismerkedjenek meg, és akár használják is. Zend esetében programunkhoz két féle API felület is tartozhat: SOAP és XML-RPC. Példa egy SOAP üzenetre: <?xml version="1.0"?> <soap:envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:header> </soap:header> <soap:body> <m:getrendelesosszeg xmlns:m="http://localhost/rendeles"> <m:objectid>3</m:objectid> </m:getrendelesosszeg> </soap:body> </soap:envelope> Az előzőekben szereplő példák XML-RPC példák voltak. A mi szempontunkból, most lényegtelen a kettő közötti különbség SOAP és XML- RPC. Bővebben olvashatunk mindkettőről az alábbi címeken: http://en.wikipedia.org/wiki/xml-rpc http://en.wikipedia.org/wiki/soap Ha a programunkat ezek egyikére vagy mindkettőre felkészítjük később, könnyebb dolgunk lesz ha kommunikálni akarunk más programokkal. $client = new Zend_XmlRpc_Client('http://localhost/xmlrpc'); echo $client->call('test.sayhello'); A példából látszik, hogy megadjuk az API belépési pontját (http://localhost/xmlrpc), és utána egyszerűen a call metódussal függvényeket hívunk meg és visszakapjuk az eredményt. Az látható, hogy ez így sokkal egyszerűbb mintha nekünk kellene összeállítani az XML-t és a válasz XML-ből kiszedni a választ. Illetve hibát adni -8-9
vissza ha szintaktikailag hibás XML-t kapott a programunk. A fenti példában már stringként kapjuk vissza, a választ pl.: hello. Ahhoz, hogy a mi programunk is tudjon fogadni API kéréseket nekünk is meg kell írni a szerver oldali funkciókat. Egy egyszerű példa: function md5value($value) { return md5($value); $server = new Zend_XmlRpc_Server(); $server->addfunction('md5value'); echo $server->handle(); Bővebben a Zend XML-RPC funkcióiról: http://framework.zend.com/manual/en/zend.xmlrpc.html Bővebben a Zend SOAP-ról: http://framework.zend.com/manual/en/zend.soap.html -9-9