Neobsahuje názory Henryka Laholy

API a PHP, díl druhý

v němž se stručně zmíním o zkratkách XML-RPC, REST, navrhnu jednoduchou aplikaci a její API a navrch přihodím pár odkazů

Minulý díl vás nebývale zaujal (=nikdo nic), takže vidím, že jsem zvolil opravdu dobré téma a mohu v něm pokračovat.

Zvolím nejprve ilustrační příklad – hypotetickou službu "MLP.CZ", neboli Malý Lepivý Papírek. Takový ten co se na něj napíše "Šli jsme na oběd" a nalepí se kolegovi na monitor. Tak něco podobného, ale na webu. Online poznámkový notes. Třeba nějak takhle. (Mimochodem, všimli jste si, že jsem už v roce 2004 udělal AJAX aplikaci, a to bez HttpXMLRequest ?) :)

Hypotetická služba mlp.cz funguje tak, že si zaregistrovaný uživatel může napsat krátkou poznámku a nějak ji nazvat. Může existující poznámky číst, měnit a mazat (takový CRUD). Jednoduchá služba, ale postačí k ilustraci, takže budeme pro tuto chvíli předpokládat, že je i užitečná. :)

Autor téhle služby si řekne, že by bylo fajn, kdyby byla jeho služba použitelná i z jiných webů nebo z desktopových aplikací. Rozhodne se tedy nabídnout možnost přímého přístupu ke službě, tedy ne jen přes WWW prohlížeč / HTML interface. Jak na to půjdu já, když budu autorem podobné služby?

Nejprve budu přemýšlet. Vím, vypadá to divně, ale zjistil jsem, že dva dny civění do stropu a přemýšlení nad problémem je mnohem produktivnější než týden pilného bušení do klávesnice. I když ve firmách manageři těžce nesou pohled na zevlujícího programátora, tak je to tak.

Když se dostatečně zamyslím, přijdu nejspíš na to, že budu potřebovat, aby API poskytovalo datové operace, tedy vytvoření poznámky, její smazání, přečtení a úpravu (CRUD); musí poskytovat i nějakou možnost získání seznamu uložených poznámek, samosebou taky nějakou autentifikaci uživatele a když budu v opravdu hodně dobrém rozmaru, tak i možnost vytvoření nového uživatele.

API tedy bude poskytovat nějaké funkce createNote(), deleteNote(), retrieveNote(), updateNote(), getNotes(), verifyUser() a createUser().

Teď je načase rozmyslet si, jakým způsobem k nim budou klienti přistupovat. Je jasné, že jde v podstatě o volání funkce, které jsou předány nějaké parametry a která vrátí nějaký výsledek. Jen je potřeba zařídit, aby tu funkci mohla volat i vzdálená aplikace, která běží na jiném stroji. Jak?

Jedním ze standardů pro volání vzdálených funkcí je XML-RPC (XML Remote Procedure Call). Spočívá v tom, že klient pošle aplikaci (serveru) HTTP požadavek POST a v jeho těle předá přesně specifikovaný XML soubor. Ten obsahuje jméno požadované metody a její parametry. Dejme tomu, že klient požaduje smazání poznámky číslo 42 uživatele "pepa", který má heslo "1234". Pošle tedy takovýto požadavek:

POST /api.php HTTP/1.0
User-Agent: MojeAplikace/1.1
Host: www.mlp.cz
Content-Type: text/xml
Content-length: 181

<?xml version="1.0"?> 
<methodCall>
 <methodName>deleteNote</methodName>
 <params>
  <param>
   <value><string>pepa</string></value>
  </param>
  <param>
   <value><string>1234</string></value>
  </param>
  <param>
   <value><int>42</int></value>
  </param>
 </params>
</methodCall>

 


Jak je vidět, požadavek je poslán na server www.mlp.cz a je poslán skriptu api.php. "www.mlp.cz" je v terminologii XML-RPC hostitel (host) a "/api.php" je cesta k tzv. koncovému bodu (endpoint). Endpoint skript si převezme informace z HTTP požadavku, zjistí co vlastně klient chce, požadované provede a vrátí výsledek – opět jako XML soubor:

<?xml version="1.0"?>
<methodResponse>
 <params>
  <param>
   <value><boolean>true</boolean></value> 
  </param> 
 </params> 
</methodResponse>


Návratová hodnota je tedy typu boolean a v tomto případě nejspíš požadavek dopadl dobře, protože je true. Pokud došlo k nějaké chybě, tak skript vrátí chybové hlášení:

<?xml version="1.0"?> 
<methodResponse>
 <fault>
  <value>
   <struct>
    <member>
     <name>faultCode</name> 
     <value><int>4</int></value> 
    </member>
    <member>
     <name>faultString</name>
     <value><string>Bad password.</string></value> 
    </member> 
   </struct> 
  </value> 
 </fault> 
</methodResponse>


XML-RPC tedy definuje, jakým způsobem mají být předávány hodnoty a umožňuje posílat kromě skalárních typů (integer, string, boolean, datetime nebo Base64 encoded data) i pole nebo struktury. Pokud vás zajímají další informace, tak se koukněte do Specifikace XML-RPC. Pro PHP existuje několik knihoven, já používám tuhle. Obsahuje jednak několik příkladů jak vytvořit XML-RPC server nebo XML-RPC klienta a v EXTRAS balíčku nabízí i pár zajímavých funkcí (např JSONRPC nebo rozšíření XMLRPC pro AJAX).

XML-RPC (a jeho následovník SOAP) je standardní způsob pro volání vzdálených procedur, není omezen jen na webové aplikace. Používá jej například Blogger API či MovableType API a umožňuje "vzdáleně" volat např. funkci na publikování článku. Ovšem pro mou ukázkovou aplikaci je to tak trošku "kanón na wwwrabce".

Další, v současné době stále populárnější, metodou používanou pro API webových služeb je takzvaný REST. REST nahlíží na webovou službu jako na souhrn zdrojů dat (resources), z nichž každý má svou URL a požadovaná operace je určena typem HTTP požadavku. Příklad:

http://www.mlp.cz/pepa/notes/ – poznámky uživatele "pepa"
http://www.mlp.cz/pepa/notes/42 – poznámka 42 uživatele "pepa"

Pokud chce klient získat informaci z daného zdroje, pošle HTTP požadavek GET na dané URL. Pokud chce klient vytvořit data, pošle požadavek POST. Požadavkem DELETE vybraný zdroj smaže a požadavkem PUT jej upraví. O výše zmíněné smazání poznámky 42 tedy klient požádá zhruba takovýmto HTTP požadavkem:

DELETE /pepa/notes/42 HTTP/1.1
User-Agent: MojeAplikace/1.0
Host: www.mlp.cz


Píšu ZHRUBA, protože je jasné, že takto by bylo mazání velice, řekněme, liberální... :) Je potřeba nějak ověřit, že ten, kdo chce přistupovat k datům, má taky právo k nim přistupovat. O autentizaci uživatele ale až příště.

Pro inspiraci můžete kouknout na REST implementaci SQL operací: PHPRESTSQL

Pro obzvláštní nedočkavce tu mám ještě odkaz na velmi užitečný web: Programmable Web APIs  – až bude v každé kategorii alespoň jeden český zástupce, tak budeme moct mluvit o nějakém nástupu moderních webových služeb v Česku.

A dva tipy na závěr, které se budou při programování API hodit:

echo $_SERVER['REQUEST_METHOD'];
vypíše typ HTTP požadavku (GET, POST, ...)

echo join('',file('php://input'));
vypíše tělo HTTP požadavku v surové podobě

 

Dne 9.02.2007

Twittni

Přidej do: Přidat na Conota Linkuj si ! asdf.sk StumbleUpon Toolbar Stumble It!

Komentáře

[1] (Piki - WWW) 09.02.2007, 21:27:45 [X] [D]
Sledujem, že ML of P prišla k API ani nevie ako, knižnica jedna nehypotetická.

[2] (Henry ) 09.02.2007, 21:50:24 [X] [D]
Pekny serial, jen co je pravda.

[3] (rybicka ) 10.02.2007, 04:45:16 [X] [D]
chtel jsem reagovat uz u prvniho dilu, ale nestihl jsem, omlouvam se.
dovolil bych si protestovat proti predchozi definici "Web 2.0". sice si taky myslim, ze je to velmi osklivy buzzword, ale dal uz se neshodneme.
Podle mne je obecne prijimana definice "Web 2.0" zalozena na propojovani lidi, komunit, nikoliv programu.
Takze muze byt uspesny "Web 2.0" projekt, ktery dava dohromady spousty lidi, vytvari mezi nimi skupiny, vztahy etc, a presto nemusi nijak komunikovat s okolim, poskytovat nejake API.
Prikladem je treba Youtube(prvni a zatim posledni vydelecna w2.0 aplikace) - zakladem je sdileni videi, posilani si odkazu na ne. to ze si nejake video muzete vlozit do sve stranky je naprosto minoritni prvek.
ja osobne vidim w2.0 jako slepou vetev vyvoje internetu. takove male ostruvky komunit, ktere mezi sebou nijak nekomunikuji.
naopak, to co popisujete vy (API do kazde rodiny!) bych videl jako naprosto odlisnou vetev vyvoje.
to je to, co spoji ty ostruvky. to je to, co by nam mohlo ulehcit zivot.
ale to s webem 2.0 nema nic spolecneho - to je prakticka nadstavba, kterou dnesni "vizionari" uspesne ignoruji.
a aby takove api bylo uspesne, bylo by vhodne mit nezavislou autorizacni autoritu, ktera by mela otevrene api:). ale to je na delsi debatu.
dusledne propojovani webovych aplikaci pomoci api opravdu neni "Web 2.0" - spis to bude "Web 3.0";)

omlouvam se za dlouhy prispevek, ale tohle tema mi v posledni dobe silne lezi v hlave.

[4] (Arthur Dent ) 10.02.2007, 07:37:07 [X] [D]
[3] No vidíte... Vy říkáte "komunity". Na jiném místě se se mnou hádali, že "Web2.0" znamená aplikační web, "jednoduché stránky" a sdílené aplikace a ještě jinde jsem se dočetl, že jde o "změnu paradigmatu" a o to, že obsah vytváří konzumenti.

Čili co člověk, to názor. A pokud nemá "termín" obecně přijatý význam, tak je každá definice správná - tedy i ta moje. I ta Vaše. :)

Ale jinak - já netvrdím, že "Web2.0 = API". Já tvrdím, že API je ta tečka mezi dvojkou a nulou, tedy to, co stojí nenápadně v pozadí a bez čeho by w2.0 ani nevznikl. O tom, že API bude užitečné i v době, kdy "Web2.0" bude mrtvý výraz, o tom není sporu. :)

[5] (rony ) 10.02.2007, 12:56:04 [X] [D]
ja som nikto? :-) alebo ti, co su presvedceni, ze API existuje a veria v jeho existenciu su nezaujimave publikum? ;-)))

[6] (rony - WWW) 10.02.2007, 13:01:19 [X] [D]
naozaj vdaka, ze si rychlokvasenym CZ/SK projektov predviedol, co im to vlastne chyba v tych ich bleskovo vymalovanych webovkach :-)

[7] ach so (rony - WWW) 10.02.2007, 17:30:45 [X] [D]
[3] par bodov k tvojmu komentaru :-)
* http://www.youtube.com/dev

nechcem tvrdit, ze tym odkazom som zmietol vsetky tvoje tvrdenia zo stola ale minimalne som ukazal, ze uspesnost youtube je AJ v tom, ze nan nenarazite iba na webe youtube ale na milionoch stranok. A to je zaklad jeho uspesnosti. Spociva prave v moznostiach, ktore popisuje Arthur - na ICQ sme sa o tom chvilu rozpravali a aj moznost aby aplikacia umoznovala vytvaranie "vkladanych" kuskov kodu do cudzich stranok - tak aj ta suvisi s aplikacnym "myslenim" a odtial je uz krok k vytvoreniu hodnotneho programatorskeho API.

celkovo nesuhlasim s vyznenim tvojho komentara a nemozem to pre kratkost casu cele rozpisat v com je tvoj pohlad podla mojho videnia mimo.

tvrdim ale, ze pokial niekto chce vytvorit naozaj uspesny projekt, tak by sa ml zamysliet, ci mu na to staci naozaj iba webova stranka s danou url, kam mu budu ludia chodit z webovych prehliadacov. To myslim dnes uz zdaleka nestaci. Staci spomenut RSS a vieme, kde sme.

[8] (rybicka ) 12.02.2007, 22:46:52 [X] [D]
[4]
pravda, definic je vic nez dost:)

proste mi prisel ten uvod s web2.0 zbytecny. ale to je slovickareni, nema cenu resit vic.

kazdopadne super serial o api. diky za nej:)