giovedì 28 novembre 2013

API RESTful con Codeigniter usando codeigniter-restserver


Nel post precedente ho mostrato come creare un semplice sistema API con il solo metodo GET. Ma se volessimo un server API che risponda secondo lo standard RESTful, dovremmo gestire anche i metodi POST, PUT e DELETE.
In particolare, lo standard consiglia di utilizzare:
  • GET per richieste di lettura di una risorsa
  • POST per richieste di creazione di una risorsa
  • PUT per richieste di modi ca di una risorsa
  • DELETE per richieste di eliminazione di una risorsa 
 Per fare questo velocemente e possibile appoggiarsi ad una libreria di terze parti, codeigniter-restserver.

Installazione

Il primo passo è ovviamente scaricare il pacchetto dalla pagina github della libreria. Il pacchetto includerebbe anche CodeIgniter, ma è molto probabile che si voglia integrare restserver in un progetto codeigniter gi à esistente. In questo caso è su fficiente copiare i files
application/libraries/Format.php
application/libraries/REST_Controller.php
application/config/rest.php
nella propria directory application, e ricordarsi di caricare automaticamente la classe REST_Controller come libreria nel fi le di con gurazione
application/config/autoload.php
Per personalizzare le opzioni di restserver, basta modi care l'apposito fi le precedentemente copiato:
application/config/rest.php

Funzionamento di base

Per il buon funzionamento del sistema è necessario creare controller che estendono la classe base REST_Controller. La libreria elabora le richieste sulla base del metodo HTTP utilizzato e della risorsa (controller), eseguendo la funzione corrispondente all'insieme dei due elementi, sempre seguendo la logica CodeIgniter. Per spiegarmi meglio, ipotizziamo di avere il seguente controller:
class News extends REST_Controller
{
    public function index_get()
    {
        // Lettura delle news
    }

    public function index_post()
    {
        // Crea una news
    }
 
 public function index_put()
    {
        // Modifica una news
    }
 public function index_delete()
    {
        // Elimina una news
    }
}
Una richiesta del tipo
GET http://www.example.com/news
comporterà l'esecuzione della funzione index_get, index perché l'url è senza una funzione specificata (news è direttamente il controller) e get perché il metodo HTTP utilizzato è, appunto, GET.

L'accesso ai parametri è garantito dalle funzioni get, post e put.
$this->get('id'); //mappatura di $this->input->get()
$this->post('id'); //mappatura di $this->input->post() 
$this->put('id'); 
Per i parametri del metodo DELETE, poiché lo standard non li prevede, è sufficiente gestirli direttamente dalla funzione richiamata dal controllore:
public function index_delete($id)
    {
        $this->response(array(
            'returned from delete:' => $id,
        ));         
    }

E' possibile inviare in output una struttura dati con la funzione response, gestendo anche la risposta HTTP direttamente (opzionale). In questo modo la libreria si preoccuperà di formattare la risposta a seconda dello standard impostato nella configurazione (io consiglio JSON). Inoltre, gestendo le risposte HTTP, è possibile utilizzare codici appropriati come il 201 per HTTP 201 Created e 404 per HTTP 404 Not Found (in quest'ultimo caso il primo parametro sarà una risorsa vuota, come ad esempio un array senza elementi).
public function index_post()
{
    // ...crea una news

    $this->response($news, 201); // Manda la risposta HTTP 201
}
Queste sono i tips principali per lo sviluppo di un sistema API con codeigniter-restserver. Non ho parlato per motivi di tempo delle altre caratteristiche della libreria, quali la gestione di API Keys, la gestione dell'autenticazione ecc. per le quali rimando direttamente al sito ufficiale.

mercoledì 27 novembre 2013

Un semplice sistema API GET CodeIgniter con risposta JSON

In questo post volevo descrivere una implementazione relativa ad un sistema API che usa esclusivamente il metodo HTTP GET, sempre in ottica di progetti web strutturati con una netta separazione tra vista (lato client) e controllo (lato server).
Il mio framework php preferito (CodeIgniter) gestisce in modo nativo le richieste con metodo HTTP GET, quindi creare un semplice sistema di API a sola lettura è molto semplice. Ipotizziamo di creare una sottocartella chiamata api nella cartella controller, e di posizionarvi dentro i vari controller che rispecchieranno le risorse delle API.

application
   |- controllers
      |- api
         |- news.php

A questo punto sappiamo che CodeIgniter gestirà che richieste del tipo
http://www.example.com/api/news/getAll
http://www.example.com/api/news/getSingle/12
richiedendo l'esecuzione del controller news.php che compare nell'albero di esempio, con i metodi getAll senza parametri e getSingle con un parametro GET valorizzato a "12".
Vediamo quindi il codice del controller:
class News extends CI_Controller {

 public function getAll()
 {
  $query = $this->db->get('news');
  $elenco_news = array();
  foreach ($query->result() as $row)
  {
       $news = new stdClass();
       $news->id = $row->id;
       $news->titolo = $row->titolo;
       $news->contenuto = $row->contenuto;
       array_push($elenco_news, $news);
  }
  echo json_encode($elenco_news);
 }
 
 public function getSingle(id)
 {
  $this->db->from('news')->where('id',$id);
  $query = $this->db->get();
  $row = $query->row(); 
  $news = new stdClass();
  $news->id = $row->id;
  $news->titolo = $row->titolo;
  $news->contenuto = $row->contenuto;
  echo json_encode($news);
 }

}
Sarà sufficiente quindi creare un controller per ogni tipo di risorsa (ad esempio news, eventi, banner) ed i relativi metodi, ricordandosi di strutturare le risposte in formato JSON come da esempio.

martedì 19 novembre 2013

Chiamate AJAX cross domain JQuery ad API JSON

Ultimamente i progetti web-based sono strutturati tutti in modo simile, ossia con un backend API e un frontend che interroga le API, solitamente in ajax.
In particolare i miei progetti sono caratterizzati da PHP + CodeIgniter lato API (con risposte JSON), e jQuery lato frontend.
Il jQuery si comporta magnificamente con le chiamate Ajax, ma qualche giorno fa mi è capitato il caso di interrogare le API da un dominio diverso da quello del server dove risiedono. Il problema è relativo al fatto che jQuery non permette chiamate ajax cross-domain con tipologia JSON oppure testo normale, come restrizione di sicurezza.
Leggendo la documentazione, viene specificato che le chiamate cross-domain sono possibili solo per la tipologia di scambio dati JSONP.
Ma che diavolo è JSONP? Il fantomatico JSON with Padding è un formato di interscambio dati basato su due semplici punti:
- una funzione di callback
- come parametro della precedente, il JSON che intendiamo trasmettere.
Ad esempio, questo è JSONP
funzionecallback({"status":"ok"})
Mentre il rispettivo JSON sarebbe
{"status":"ok"}
La funzione di callback lato client si può specificare mediante un apposito comando di configurazione di $.ajax oppure lasciare che sia jQuery a decidere il nome della callback ed a inviarlo come parametro GET (chiamato appunto, callback) alle API.
Vediamo quindi nel dettaglio come gestire le nozioni precedentemente apprese. Lato API, vediamo un semplice esempio in cui vogliamo come output un oggetto di prova contenente id e descrizione:
$obj = new stdClass();
$obj->id = "56321564";
$obj->descrizione = "Prova di descrizione";

if ($_GET['callback']!='') {
    echo $_GET['callback'].'('.json_encode($obj).')';
} 
else {
    echo json_encode($obj);
}
In questo modo siamo in grado di capire in maniera molto semplice (senza header http) in che formato mostrare il risultato: se esiste un parametro GET chiamato callback, lo script deve utilizzare il formato JSONP, altrimenti il JSON normale.
Ed ora la parte frontend, in jQuery:
var apiUrl = "http://www.example.com/api/example.php";
$( document ).ready(function() {
    $.ajax({
        type: "GET",
        url: apiUrl,
        dataType: "jsonp" ,
        crossDomain: true,
    }).done(function( json_response ) {
        console.log(JSON.stringify(json_response));
    }).fail(function(jqXHR, textStatus) {
        $('#result').html( "Request failed: " + textStatus + " " + jqXHR.status );
    });

});
La quale produrrà il risultato voluto in console:
{"id":"56321564", "descrizione": "Prova di descrizione"}
Importanti sono l'opzione dataType nella chiamata Ajax impostata su jsonp e crossDomain impostato su true.