cURL, Php e l’API di delicious

Letto l’ultimo post?

Se non l’avete letto, vi consiglio di darci un’occhiata prima di passare a questo.

Dopo aver gettato le basi del discorso sulla libcurl, cominciamo il viaggio tra le APIs di alcune tra le webapps più popolari. Qui parliamo di delicious.

delicious

Non farò cenno alcuno a cosa sia il social bookmarking e la folksonomy; non parlerò affatto degli aspetti concettuali e sociali dei tag e dei machinetags. Per questi discorsi, indispensabili e propedeutici allo sviluppo di un’applicazione che utilizzi le API di delicious, rinvio ad altre fonti. Qui si parla solo di codice!

Sarà codice estremamente semplice e poco raffinato, ma ci poniamo solo obiettivi dimostrativi.

Composizione delle URL di richiesta

L’API di delicious viene invocata con semplici URL (abbiamo già parlato del formato REST nel post precedente).

La URL sarà composta dall’endpoint REST, comune a tutte le richieste, dal metodo invocato e dai parametri obbligatori o facoltativi che completano la richiesta.

La URL dell’endpoint sarà sempre:

https://api.del.icio.us/v1/

Ciò significa che tutte le nostre richieste avranno questa prima parte di URL in comune. Come potete notare, il protocollo di trasmissione è https. Qui non ne parlo, rinviandovi a letture più importanti. Lo faccio notare solo perchè, se non usate un sistema Linux (locale o remoto che sia), dovrete istallarvi la vostra versione di cURL (ne abbiamo parlato nel post precedente). Per accedere all’API di delicious sarà indispensabile scaricare la versione con supporto SSL.

La seconda parte dell’URL specificherà il metodo invocato. Se desideriamo avere una lista di bokmarks aggiunti di recente, utilizzeremo il metodo posts/recent. La nostra URL diventa:

https://api.del.icio.us/v1/posts/recent

Così, però, avremo solo una lista ordinata cronologicamente. Specificando dei parametri di richiesta, stabiliremo i filtri che consentiranno di raffinare la ricerca.
Se vogliamo avere tutti i bookmarks etichettati con la parola “delicious”, aggiungeremo il parametro tag=delicious. Possiamo anche specificare più tag: basterà concatenarli col silbolo +: tag=delicious+api.
La URL diventa:

https://api.del.icio.us/v1/posts/recent?tag=delicious

Ovviamente, possiamo aggiungere anche altri parametri. Per una lista completa, date un’occhiata alla guida ufficiale: http://delicious.com/help/api.

Avete provato a digitare la URL nel browser? Take a try… avrete un listato XML.

User Agent e utente

Non possiamo parlare di User Agent, ovviamente. Sapete tutti di cosa si tratta (se avete dei dubbi, date una lettura qui e qui).
Diciamo solo che delicious gradisce sapere chi bussa alla porta, prima di aprire. Per questo è opportuno specificare il nome dell’applicazione che sta invocando l’API tra i parametri trasmessi via cURL.

Possiamo forzare il nome del nostro browser preferito (“Mozilla/5.0 (Windows; U; Windows NT 6.0; en-US; rv:1.9.0.6) Gecko/2009011913 Firefox/3.0.6”), oppure specificare il nome della nostra applicazione (“Mash-up con cURL e PHP”).

Oltre a specificare lo user agent, è necessario autenticarsi col proprio nome utente e pw (questo significa che se non avete un account, delicious non vi darà accesso all’API).

Stabiliamo la connessione

Fatte le debite premesse, passiamo al codice:

$url = "https://api.del.icio.us/v1/posts/recent?tag=delicious&count=20";
$user_agent = "Mozilla/5.0 (Windows; U; Windows NT 6.0; en-US; rv:1.9.0.6) Gecko/2009011913 Firefox/3.0.6";
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_USERAGENT, $user_agent);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");
$result = curl_exec($ch);
curl_close($ch);

Oltre a richiedere i bookmarks etichettati con la parola “delicious”, stabiliamo che ci vengano mostrati i 20 più recenti. Se non stabilissimo questo parametro, delicious ce ne restituirebbe 15. Il valore massimo di count è 100.

Manipoliamo i dati

$posts = simplexml_load_string($result);
foreach ($posts->post as $bookmark) {
  $href = $bookmark['href'];
  $hash = $bookmark['hash'];
  $description = $bookmark['description'];
  $tags = explode(" ", $bookmark['tag']);
  $time = $bookmark['time'];
  $extended = $bookmark['extended'];
}

Un giorno mi dedicherò alle funzioni di Php5 per la manipolazione dei dati in formato XML. Ma non oggi…
L’opzione passata a cURL

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

stabilisce che i dati vengano passati come stringa di testo e non come file. In questo modo saranno accessibili via Php5 con la funzione simplexml_load_string().

That’s all falks. Non c’è altro da fare che mostrare l’output a video. E la cosa bella è che accederemo alle altre webapps cui ho accennato nel precedente post, quasi nello stesso modo: definizione dei parametri, accesso a cURL, trasmissione della richiesta, manipolazione dei dati.

Forse sono stato un po’ sbrigativo. Ho voluto più che altro tracciare delle linee guida per consentire poi di approfondire il discorso, rinviandovi alle sedi più opportune.

Un articolo senza dubbio più completo ed esauriente sull’API di delicious l’ho scritto per ioProgrammo, ed è in edicola proprio in questi giorni. Su ioProgrammo, inoltre, ho offerto lo spunto per un simpatico mash-up delicious/Google Maps.

Il riferimento obbligatorio, comunque, è la guida ufficiale: http://delicious.com/help/api

Continua …

Annunci