Le API Rest di Facebook

Nota: le Graph Api saranno oggetto di un'altra lezione

Le API (Application Programming Interface) sono l'ennesimo sforzo fatto dal team di Facebook affinché i contenuti sociali divengano facilmente integrabili nelle nostre applicazioni. Tecnicamente, le API Facebook, come la stragrande maggioranza delle API dei più moderni servizi web, seguono i dettami dell'architettura REST.

L'acronimo REST sta per REpresentational State Transfer, un tipo di architettura software in cui un client e uno o più server sono i principali attori. Il client richiede al server una risorsa, il server si occuperà di preparare lo stato di quella risorsa in un formato predeterminato (XML, Json solo per citarne alcuni) e ritornarlo al client.

In uno scenario quanto più semplice possibile un servizio web RESTful è realizzabile sfruttando semplicemente il protocollo HTTP e sue funzioni come GET e POST senza strumenti supplementari. Facebook non è da meno.

Visitando la pagina ufficiale di documentazione riguardante le API troveremo una catalogazione dei vari metodi in base all'area di utilizzo. Siccome tale divisione ai fini didattici è ininfluente l'unico distinguo che faremo tra i vari metodi sarà fatto tra API wrapper e non.

Le API wrapper sono tutte quelle API il cui risultato generato può essere ottenuto, senza perdita di significato, mediante un'appropriata interrogazione FQL. Ad esempio, il metodo events.getMembers è una API wrapper e restituisce la lista di tutti gli identificativi utente (più altre informazioni addizionali) che parteciperanno ad un determinato evento, l'interrogazione FQL omologa è:

SELECT uid, eid, rsvp_status
FROM event_member
WHERE eid=eid

Il risultato della chiamata API e quello dell'interrogazione FQL precedente produrranno lo stesso output.

Le API che non rientrano nella categoria precedente sono tutte quelle che non ritornano alcun tipo di informazione "sociale" (l'unico ritorno di tali API sono codici di errori o di conferma), in ragione di questo, il loro unico scopo è quello di inserire nuovi elementi all'interno del mondo Facebook. Uno dei metodi più interessanti è stream.publish, che ci permette di pubblicare sulla bacheca, nostra, di un nostro amico, di un gruppo o di una fan page dei contenuti multimediali da noi definiti. L'esempio più banale che possiamo realizzare è l'invio di un messaggio testuale sulla nostra bacheca, grazie al PHP e all'API appropriata.

<!-- FBML: Richiesta permessi di pubblicazione --> 
<?
     // PHP: Inizializzazione API
     $testo = "Questo è un messaggio di prova.";
     $API->api_client->stream_publish($testo);
?>

Come si nota dal listato precedente, sono state omesse delle parti di codice, una parte FBML per autorizzare la pubblicazione del post in bacheca e una parte in PHP per importare le librerie e inizializzare le API. Nella parte della guida in cui affronteremo da zero la creazione di un applicativo verrà spiegato cosa inserire al posto dei commenti.

Anche questa volta non ci dimenticheremo della wiki ufficiale, il metodo stream.publish ha numerosi parametri, qui possiamo capire quali sono quelli opzionali, quali sono quelli obbligatori e possiamo leggere numerosi esempi, anche in un linguaggio diverso dal PHP.

Tra i parametri più interessanti che conosceremo visitando il link precedente ci sono senz'altro attachment, action_links e target_id. I parametri attachment e action_links vanno scritti in formato JSON e permettono, il primo, di inserire elementi multimediali al messaggio, il secondo, di aggiungere link addizionali accanto ai classici "Commenta" e "Mi Piace".

Il parametro target_id accetta un id numerico e andrà utilizzato se il messaggio non va postato sulla nostra bacheca ma sulla bacheca di un nostro amico, gruppo, evento o fan page. Quello che segue è un esempio in cui useremo il metodo stream.publish() - da notare che il punto della dot notation viene sostituito da un underscore divenendo stream_publish() - in accoppiata ad attachment e action_links.

 
<!-- FBML: Richiesta permessi di pubblicazione --> 
<?
// PHP: Inizializzazione API
$testo = 'Un album imperdibile';
$attachment = array(
   'name' => 'Consigli musicali',
   'caption' => '{*actor*} ti consiglia di ascoltare l'album:',
   'description' => 'Tom Waits - Closing Time',    
   'media' => array(
      array(
         'type' => 'image',
         'src' => 'http://www.onetimesone.com/top-lists/closing-time.jpg',
         'href' => 'http://www.amazon.com/Closing-Time-Tom-Waits/dp/B000002GYR'
                     )
           )
                     );
$action_links = array(
          array(
     'text' => 'Vai all'applicazione',
     'href' => 'http://apps.facebook.com/consigli_musicali'
          )
      );
// trasforma gli array PHP in oggetti JSON
$attachment = json_encode($attachment);
$action_links = json_encode($action_links);
// effettua chiamata API
$API->api_client->stream_publish($testo, $attachment, $action_links);
?>

La variabile $testo fa sì che una stringa testuale venga apposta allo streaming, come già accadeva nel caso precedente. Le novità, stavolta, sono gli oggetti $attachment e $action_links. Grazie all'attachment inseriremo un'immagine più vari campi supplementari al semplice streaming testuale. Interessante, in questo caso, è il segnaposto {*actor*}, utilizzabile nel campo caption, che in fase di esecuzione del codice verrà sostituito con il nome proprio dell'utente che ha richiamato lo script. L'elemento media è l'elemento multimediale, viene specificato un type in questo caso specifichiamo trattasi di un'immagine, src l'indirizzo dove l'immagine è memorizzata e href è il link dove l'immagine conduce, in questo caso la pagina di Amazon che espone il CD.

L'oggetto action_links, invece, ci permette di arricchire la lista dei link classici, aggiungendone di personalizzati, in questo caso abbiamo aggiunto un link chiamato "Vai all'applicazione". I tre oggetti che abbiamo preparato verranno poi inviati all'API stream_publish(). Ecco come verrà visualizzato il nostro post.

Con questo esempio si conclude la parte introduttiva alle API di Facebook, queste ed altre API, verranno affrontate con maggior dettaglio nella parte pratica della guida.